class sap.ui.comp.smartform.SmartForm

Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/comp/smartform/SmartForm
Application Component: CA-UI5-CMP

The SmartForm control renders a form (sap.ui.layout.form.Form). When used with the SmartField control the label is taken from the metadata annotation sap:label if not specified directly.

Warning: Do not put any layout or other container controls into the GroupElement. Views are also not supported. This could damage the visual layout, keyboard support and screen-reader support.


Constructor

Constructor for a new smartform/SmartForm.

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.ui.comp.smartform.SmartForm(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
checkButton boolean false

Specifies whether a check button is added to the toolbar.

Visibility: public
editTogglable boolean false

If set to true, a button to toggle the editable property is shown in the toolbar.

Visibility: public
editable boolean false

Applies a device-specific and theme-specific line height and label alignment to the form rows if the form has editable content. If set, all (not only the editable) rows of the form will get the line height of editable fields.

The labels inside the form will be rendered by default in the according mode.

Note: The setting of this property will be passed to all SmartField controls inside the form, so they will be editable if the form is editable.

Warning: The setting of this property will not be passed to controls other than SmartField. For example, Input controls in a form with editable set to false are still editable.

If controls other than SmartField controls are used, and the edit mode of their control is not set correctly, this might lead to visual issues. The labels and fields might be misaligned, the labels might be rendered in the wrong mode, and the spacing between the single controls might be wrong. Also, controls that do not fit the mode might be rendered incorrectly.

Visibility: public
entityType string

CSV of entity types for which the flexibility features are available.
For more information about SAPUI5 flexibility, refer to the Developer Guide.
Note: No validation is done. Please ensure that you do not add spaces or special characters.

Visibility: public
expandable boolean false

Specifies whether the control is expandable. Per default the control is not rendered as expanded.

Visibility: public
expanded boolean

If expandable, this property indicates whether the state is expanded or not. If expanded, then the toolbar (if available) and the content is rendered; if expanded is false, then only the headerText/headerToolbar is rendered.

Visibility: public
flexEnabled boolean true

Specifies whether the form enables flexibility features, such as adding new fields.
For more information about SAPUI5 flexibility, refer to the Developer Guide.

Visibility: public
horizontalLayoutGroupElementMinWidth int

Specifies the minimal size in pixels of all group elements of the form if the horizontal layout is used.

Visibility: public
ignoredFields string

CSV of fields that must be ignored in the OData metadata by the SmartForm control.
Note:
No validation is done. Please ensure that you do not add spaces or special characters.

Visibility: public
importance sap.ui.comp.smartform.Importance Low

Specifies which smart fields will be visible inside the SmartForm.

If set to high, only smart fields with high importance will be visible.

If set to medium, only smart fields with high and medium importance will be visible.

If set to low (default), all the smart fields will be visible regardless of their importance.

Note: If a smart field is annotated as mandatory or hidden, its visibility will not be affected by the importance property.

Since: 1.87.

Visibility: public
title string

Title of the form.

Note: The title is rendered with a theme-dependent default level. As the SmartForm control cannot know the structure of the page, this might not fit the page structure. In this case provide the title using a Title control and set its level to the required value. Add this title to a Toolbar control and assign it to the SmartForm using the customToolbar aggregation.

Visibility: public
useHorizontalLayout boolean

Specifies whether the groups are rendered in a ResponsiveLayout with the label above the field. Each group is rendered in a new line.

Note: This property should no longer be used. To arrange the fields in columns, ColumnLayout should be used in the layout aggregation.

Note: The value of this property will be passed on to the useHorizontalLayout property of all Group and GroupElement elements.

Visibility: public
validationMode sap.ui.comp.smartform.SmartFormValidationMode Standard

Controls the SmartForm validation mode. The default mode handles only nested SmartField controls with synchronous validation. If the SmartForm should also handle controls with asynchronous validation the property should be set to Async mode which is the recommended mode to be used as all types of nested fields validation are handled.

Note: Using Async mode the method check will return a promise instead of an array.

Note: Using Async mode the event checked will be called asynchronously when all the nested SmartField validations are executed.

Since: 1.81.

Visibility: public

Aggregations

Default Aggregation: groups

Name Cardinality Type Description
content 0..1 sap.ui.core.Control

Content to be rendered.

customToolbar 0..1 sap.m.Toolbar

An additional toolbar that can be added by the users, which can contain further custom buttons, controls, etc.

Note: If a special title is required inside the Toolbar, it must be added as content to the Toolbar. In this case add the Title to the ariaLabelledBy association. Use the required title level to meet the visual requirements. This might be theme-dependent.

groups (default) 0..n sap.ui.comp.smartform.Group

Groups are used to group form elements.

layout 0..1 sap.ui.comp.smartform.SmartFormLayout

Layout settings to adjust the used layout.

Use ColumnLayout to have the current UI.

semanticObjectController 0..1 sap.ui.comp.navpopover.SemanticObjectController

The Semantic Object Controller allows the user to specify and overwrite functionality for semantic object navigation.

toolbar 0..1 sap.m.Toolbar

Toolbar


Associations

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

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

Since: 1.56.0.


Events Overview

Event Description
checked

This event is fired after check was performed.

editToggled

This event is fired when the editable property is toggled.

checked

This event is fired after check was performed.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
erroneousFields sap.ui.comp.smartfield.SmartField[]

An array containing all smart fields with errors

editToggled

This event is fired when the editable property is toggled.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
editable boolean

If true, the control is in edit mode


Methods Overview

Method Description
addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

addCustomData

Adds some customData into the aggregation customData.

Note: customData that is used by the SmartField control itself is also added to the Group elements, GroupElement elements and the SmartField controls in the children hierarchy. Additional customData that is not used by the SmartField control internally might not be added.

addGroup

Adds some group to the aggregation groups.

attachChecked

Attaches event handler fnFunction to the checked event of this sap.ui.comp.smartform.SmartForm.

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.ui.comp.smartform.SmartForm itself.

This event is fired after check was performed.

attachEditToggled

Attaches event handler fnFunction to the editToggled event of this sap.ui.comp.smartform.SmartForm.

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.ui.comp.smartform.SmartForm itself.

This event is fired when the editable property is toggled.

check

Checks smart fields for client errors.

This method is typically used to check whether the value of every text input field in edit mode is subject to data type constraints and whether the constraints are fulfilled.

A data type constraint for a bound Entity Data Model (EDM) property can be violated in many ways, for example:

  • The Nullable constraint for an EDM property typed as Edm.String is violated.
  • A user input is invalid for the bound EDM property typed as Edm.DateTime.

If this happens, the following applies:

  • A validation error state is set on the text input field.
  • A validation error message is displayed for the text input field.
  • The validation error message (possibly generated by a user input) is added to a sap.ui.core.message.MessageManager object instance if, for example, a view object instance is registered to it.
  • The text input field fires a sap.ui.base.EventProvider#event:validationError, or sap.ui.base.EventProvider#event:parseError event.

destroyCustomToolbar

Destroys the customToolbar in the aggregation customToolbar.

destroyGroups

Destroys all the groups in the aggregation groups.

destroyLayout

Destroys the layout in the aggregation layout.

destroySemanticObjectController

Destroys the semanticObjectController in the aggregation semanticObjectController.

detachChecked

Detaches event handler fnFunction from the checked event of this sap.ui.comp.smartform.SmartForm.

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

detachEditToggled

Detaches event handler fnFunction from the editToggled event of this sap.ui.comp.smartform.SmartForm.

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

sap.ui.comp.smartform.SmartForm.extend

Creates a new subclass of class sap.ui.comp.smartform.SmartForm 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.

fireChecked

Fires event checked to attached listeners.

fireEditToggled

Fires event editToggled to attached listeners.

getAriaLabelledBy

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

getCheckButton

Gets current value of property checkButton.

Specifies whether a check button is added to the toolbar.

Default value is false.

getCustomToolbar

Gets content of aggregation customToolbar.

An additional toolbar that can be added by the users, which can contain further custom buttons, controls, etc.

Note: If a special title is required inside the Toolbar, it must be added as content to the Toolbar. In this case add the Title to the ariaLabelledBy association. Use the required title level to meet the visual requirements. This might be theme-dependent.

getEditable

Gets current value of property editable.

Applies a device-specific and theme-specific line height and label alignment to the form rows if the form has editable content. If set, all (not only the editable) rows of the form will get the line height of editable fields.

The labels inside the form will be rendered by default in the according mode.

Note: The setting of this property will be passed to all SmartField controls inside the form, so they will be editable if the form is editable.

Warning: The setting of this property will not be passed to controls other than SmartField. For example, Input controls in a form with editable set to false are still editable.

If controls other than SmartField controls are used, and the edit mode of their control is not set correctly, this might lead to visual issues. The labels and fields might be misaligned, the labels might be rendered in the wrong mode, and the spacing between the single controls might be wrong. Also, controls that do not fit the mode might be rendered incorrectly.

Default value is false.

getEditTogglable

Gets current value of property editTogglable.

If set to true, a button to toggle the editable property is shown in the toolbar.

Default value is false.

getEntityType

Gets current value of property entityType.

CSV of entity types for which the flexibility features are available.
For more information about SAPUI5 flexibility, refer to the Developer Guide.
Note: No validation is done. Please ensure that you do not add spaces or special characters.

getExpandable

Gets current value of property expandable.

Specifies whether the control is expandable. Per default the control is not rendered as expanded.

Default value is false.

getExpanded

Gets current value of property expanded.

If expandable, this property indicates whether the state is expanded or not. If expanded, then the toolbar (if available) and the content is rendered; if expanded is false, then only the headerText/headerToolbar is rendered.

getFlexEnabled

Gets current value of property flexEnabled.

Specifies whether the form enables flexibility features, such as adding new fields.
For more information about SAPUI5 flexibility, refer to the Developer Guide.

Default value is true.

getGroups

Gets content of aggregation groups.

Groups are used to group form elements.

getHorizontalLayoutGroupElementMinWidth

Gets current value of property horizontalLayoutGroupElementMinWidth.

Specifies the minimal size in pixels of all group elements of the form if the horizontal layout is used.

Since 1.48.0 please do not use this property as it does not have any effect on the current layout of the <code>SmartForm</code> control.
getIgnoredFields

Gets current value of property ignoredFields.

CSV of fields that must be ignored in the OData metadata by the SmartForm control.
Note:
No validation is done. Please ensure that you do not add spaces or special characters.

getImportance

Gets current value of property importance.

Specifies which smart fields will be visible inside the SmartForm.

If set to high, only smart fields with high importance will be visible.

If set to medium, only smart fields with high and medium importance will be visible.

If set to low (default), all the smart fields will be visible regardless of their importance.

Note: If a smart field is annotated as mandatory or hidden, its visibility will not be affected by the importance property.

Default value is Low.

getLayout

Gets content of aggregation layout.

Layout settings to adjust the used layout.

Use ColumnLayout to have the current UI.

sap.ui.comp.smartform.SmartForm.getMetadata

Returns a metadata object for class sap.ui.comp.smartform.SmartForm.

getSemanticObjectController

Gets content of aggregation semanticObjectController.

The Semantic Object Controller allows the user to specify and overwrite functionality for semantic object navigation.

getSmartFields

Retrieves all the smart fields of the form.

Note: Even invisible SmartField controls are returned if the group or groupElement is visible.

getTitle

Gets current value of property title.

Title of the form.

Note: The title is rendered with a theme-dependent default level. As the SmartForm control cannot know the structure of the page, this might not fit the page structure. In this case provide the title using a Title control and set its level to the required value. Add this title to a Toolbar control and assign it to the SmartForm using the customToolbar aggregation.

getUseHorizontalLayout

Gets current value of property useHorizontalLayout.

Specifies whether the groups are rendered in a ResponsiveLayout with the label above the field. Each group is rendered in a new line.

Note: This property should no longer be used. To arrange the fields in columns, ColumnLayout should be used in the layout aggregation.

Note: The value of this property will be passed on to the useHorizontalLayout property of all Group and GroupElement elements.

Since 1.86 replaced by {@link sap.ui.comp.smartform.ColumnLayout ColumnLayout} in the <code>layout</code> aggregation.
getValidationMode

Gets current value of property validationMode.

Controls the SmartForm validation mode. The default mode handles only nested SmartField controls with synchronous validation. If the SmartForm should also handle controls with asynchronous validation the property should be set to Async mode which is the recommended mode to be used as all types of nested fields validation are handled.

Note: Using Async mode the method check will return a promise instead of an array.

Note: Using Async mode the event checked will be called asynchronously when all the nested SmartField validations are executed.

Default value is Standard.

getVisibleProperties

Returns the array of properties currently visible on the UI.

indexOfGroup

Checks for the provided sap.ui.comp.smartform.Group in the aggregation groups. and returns its index if found or -1 otherwise.

insertCustomData

Inserts some customData into the aggregation customData.

Note: customData that is used by the SmartField control itself is also added to the Group elements, GroupElement elements and the SmartField controls in the children hierarchy. Additional customData that is not used by the SmartField control internally might not be added.

insertGroup

Inserts a group into the aggregation groups.

propagateGridDataSpan

Sets default span for GridData layout of group elements when used with horizontal layout.

Note: There is no need to call this function as the update of all GroupElement elements inside the SmartForm control is triggered automatically if the GridDataSpan property of the Layout aggregation changes or the Layout aggregation is added.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllGroups

Removes all the controls from the aggregation groups.

Additionally, it unregisters them from the hosting UIArea.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

removeGroup

Removes a group from the aggregation groups.

setCheckButton

Sets a new value for property checkButton.

Specifies whether a check button is added to the toolbar.

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

Default value is false.

setCustomToolbar

Sets the aggregated customToolbar.

setEditable

Sets a new value for property editable.

Applies a device-specific and theme-specific line height and label alignment to the form rows if the form has editable content. If set, all (not only the editable) rows of the form will get the line height of editable fields.

The labels inside the form will be rendered by default in the according mode.

Note: The setting of this property will be passed to all SmartField controls inside the form, so they will be editable if the form is editable.

Warning: The setting of this property will not be passed to controls other than SmartField. For example, Input controls in a form with editable set to false are still editable.

If controls other than SmartField controls are used, and the edit mode of their control is not set correctly, this might lead to visual issues. The labels and fields might be misaligned, the labels might be rendered in the wrong mode, and the spacing between the single controls might be wrong. Also, controls that do not fit the mode might be rendered incorrectly.

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

Default value is false.

setEditTogglable

Sets a new value for property editTogglable.

If set to true, a button to toggle the editable property is shown in the toolbar.

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

Default value is false.

setEntityType

Sets a new value for property entityType.

CSV of entity types for which the flexibility features are available.
For more information about SAPUI5 flexibility, refer to the Developer Guide.
Note: No validation is done. Please ensure that you do not add spaces or special characters.

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

setExpandable

Sets a new value for property expandable.

Specifies whether the control is expandable. Per default the control is not rendered as expanded.

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

Default value is false.

setExpanded

Sets a new value for property expanded.

If expandable, this property indicates whether the state is expanded or not. If expanded, then the toolbar (if available) and the content is rendered; if expanded is false, then only the headerText/headerToolbar is rendered.

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

setFlexEnabled

Sets a new value for property flexEnabled.

Specifies whether the form enables flexibility features, such as adding new fields.
For more information about SAPUI5 flexibility, refer to the Developer Guide.

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

Default value is true.

setFocusOnEditableControl

Sets the focus on the first editable control.

setHorizontalLayoutGroupElementMinWidth

Sets a new value for property horizontalLayoutGroupElementMinWidth.

Specifies the minimal size in pixels of all group elements of the form if the horizontal layout is used.

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

Since 1.48.0 please do not use this property as it does not have any effect on the current layout of the <code>SmartForm</code> control.
setIgnoredFields

Sets a new value for property ignoredFields.

CSV of fields that must be ignored in the OData metadata by the SmartForm control.
Note:
No validation is done. Please ensure that you do not add spaces or special characters.

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

setImportance

Sets a new value for property importance.

Specifies which smart fields will be visible inside the SmartForm.

If set to high, only smart fields with high importance will be visible.

If set to medium, only smart fields with high and medium importance will be visible.

If set to low (default), all the smart fields will be visible regardless of their importance.

Note: If a smart field is annotated as mandatory or hidden, its visibility will not be affected by the importance property.

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

Default value is Low.

setLayout

Sets the aggregated layout.

setSemanticObjectController

Sets the aggregated semanticObjectController.

setTitle

Sets a new value for property title.

Title of the form.

Note: The title is rendered with a theme-dependent default level. As the SmartForm control cannot know the structure of the page, this might not fit the page structure. In this case provide the title using a Title control and set its level to the required value. Add this title to a Toolbar control and assign it to the SmartForm using the customToolbar aggregation.

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

setUseHorizontalLayout

Sets a new value for property useHorizontalLayout.

Specifies whether the groups are rendered in a ResponsiveLayout with the label above the field. Each group is rendered in a new line.

Note: This property should no longer be used. To arrange the fields in columns, ColumnLayout should be used in the layout aggregation.

Note: The value of this property will be passed on to the useHorizontalLayout property of all Group and GroupElement elements.

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

Since 1.86 replaced by {@link sap.ui.comp.smartform.ColumnLayout ColumnLayout} in the <code>layout</code> aggregation.
setValidationMode

Sets a new value for property validationMode.

Controls the SmartForm validation mode. The default mode handles only nested SmartField controls with synchronous validation. If the SmartForm should also handle controls with asynchronous validation the property should be set to Async mode which is the recommended mode to be used as all types of nested fields validation are handled.

Note: Using Async mode the method check will return a promise instead of an array.

Note: Using Async mode the event checked will be called asynchronously when all the nested SmartField validations are executed.

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

Default value is Standard.

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

addCustomData

Adds some customData into the aggregation customData.

Note: customData that is used by the SmartField control itself is also added to the Group elements, GroupElement elements and the SmartField controls in the children hierarchy. Additional customData that is not used by the SmartField control internally might not be added.

Param Type DefaultValue Description
oCustomData sap.ui.core.CustomData

the customData to add; if empty, nothing is added

addGroup

Adds some group to the aggregation groups.

Param Type DefaultValue Description
oGroup sap.ui.comp.smartform.Group

The group to add; if empty, nothing is inserted

attachChecked

Attaches event handler fnFunction to the checked event of this sap.ui.comp.smartform.SmartForm.

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.ui.comp.smartform.SmartForm itself.

This event is fired after check was performed.

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.ui.comp.smartform.SmartForm itself

attachEditToggled

Attaches event handler fnFunction to the editToggled event of this sap.ui.comp.smartform.SmartForm.

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.ui.comp.smartform.SmartForm itself.

This event is fired when the editable property is toggled.

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.ui.comp.smartform.SmartForm itself

check

Checks smart fields for client errors.

This method is typically used to check whether the value of every text input field in edit mode is subject to data type constraints and whether the constraints are fulfilled.

A data type constraint for a bound Entity Data Model (EDM) property can be violated in many ways, for example:

If this happens, the following applies:

Param Type DefaultValue Description
vSettings boolean object true

Settings object or a boolean which determines if only visible fields in visible groups should be considered

considerOnlyVisible boolean true

Determines if only visible fields in visible groups should be considered

handleSuccess boolean false

Indicates whether client error checks are performed for the current value regardless of the current error state of the text input fields of the SmartForm control. If the handleSuccess setting is set to true, the sap.ui.base.EventProvider#event:validationSuccess will be fired by every of the text input fields if their validation passes

destroyCustomToolbar

Destroys the customToolbar in the aggregation customToolbar.

destroyGroups

Destroys all the groups in the aggregation groups.

destroyLayout

Destroys the layout in the aggregation layout.

destroySemanticObjectController

Destroys the semanticObjectController in the aggregation semanticObjectController.

detachChecked

Detaches event handler fnFunction from the checked event of this sap.ui.comp.smartform.SmartForm.

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

detachEditToggled

Detaches event handler fnFunction from the editToggled event of this sap.ui.comp.smartform.SmartForm.

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.ui.comp.smartform.SmartForm.extend

Creates a new subclass of class sap.ui.comp.smartform.SmartForm 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

fireChecked

Fires event checked to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

erroneousFields sap.ui.comp.smartfield.SmartField[]

An array containing all smart fields with errors

fireEditToggled

Fires event editToggled to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

editable boolean

If true, the control is in edit mode

getAriaLabelledBy

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

getCheckButton

Gets current value of property checkButton.

Specifies whether a check button is added to the toolbar.

Default value is false.

getCustomToolbar

Gets content of aggregation customToolbar.

An additional toolbar that can be added by the users, which can contain further custom buttons, controls, etc.

Note: If a special title is required inside the Toolbar, it must be added as content to the Toolbar. In this case add the Title to the ariaLabelledBy association. Use the required title level to meet the visual requirements. This might be theme-dependent.

getEditable

Gets current value of property editable.

Applies a device-specific and theme-specific line height and label alignment to the form rows if the form has editable content. If set, all (not only the editable) rows of the form will get the line height of editable fields.

The labels inside the form will be rendered by default in the according mode.

Note: The setting of this property will be passed to all SmartField controls inside the form, so they will be editable if the form is editable.

Warning: The setting of this property will not be passed to controls other than SmartField. For example, Input controls in a form with editable set to false are still editable.

If controls other than SmartField controls are used, and the edit mode of their control is not set correctly, this might lead to visual issues. The labels and fields might be misaligned, the labels might be rendered in the wrong mode, and the spacing between the single controls might be wrong. Also, controls that do not fit the mode might be rendered incorrectly.

Default value is false.

getEditTogglable

Gets current value of property editTogglable.

If set to true, a button to toggle the editable property is shown in the toolbar.

Default value is false.

getEntityType

Gets current value of property entityType.

CSV of entity types for which the flexibility features are available.
For more information about SAPUI5 flexibility, refer to the Developer Guide.
Note: No validation is done. Please ensure that you do not add spaces or special characters.

getExpandable

Gets current value of property expandable.

Specifies whether the control is expandable. Per default the control is not rendered as expanded.

Default value is false.

getExpanded

Gets current value of property expanded.

If expandable, this property indicates whether the state is expanded or not. If expanded, then the toolbar (if available) and the content is rendered; if expanded is false, then only the headerText/headerToolbar is rendered.

getFlexEnabled

Gets current value of property flexEnabled.

Specifies whether the form enables flexibility features, such as adding new fields.
For more information about SAPUI5 flexibility, refer to the Developer Guide.

Default value is true.

getGroups

Gets content of aggregation groups.

Groups are used to group form elements.

getHorizontalLayoutGroupElementMinWidth

Gets current value of property horizontalLayoutGroupElementMinWidth.

Specifies the minimal size in pixels of all group elements of the form if the horizontal layout is used.

Since 1.48.0 please do not use this property as it does not have any effect on the current layout of the <code>SmartForm</code> control.

getIgnoredFields

Gets current value of property ignoredFields.

CSV of fields that must be ignored in the OData metadata by the SmartForm control.
Note:
No validation is done. Please ensure that you do not add spaces or special characters.

getImportance

Gets current value of property importance.

Specifies which smart fields will be visible inside the SmartForm.

If set to high, only smart fields with high importance will be visible.

If set to medium, only smart fields with high and medium importance will be visible.

If set to low (default), all the smart fields will be visible regardless of their importance.

Note: If a smart field is annotated as mandatory or hidden, its visibility will not be affected by the importance property.

Default value is Low.

getLayout

Gets content of aggregation layout.

Layout settings to adjust the used layout.

Use ColumnLayout to have the current UI.

sap.ui.comp.smartform.SmartForm.getMetadata

Returns a metadata object for class sap.ui.comp.smartform.SmartForm.

getSemanticObjectController

Gets content of aggregation semanticObjectController.

The Semantic Object Controller allows the user to specify and overwrite functionality for semantic object navigation.

getSmartFields

Retrieves all the smart fields of the form.

Note: Even invisible SmartField controls are returned if the group or groupElement is visible.

Param Type DefaultValue Description
bConsiderOnlyVisibleGroups boolean true

Determines if only visible groups are taken into account

bConsiderOnlyVisibleGroupElements boolean false

Determines if only visible groupElement elements are taken into account

getTitle

Gets current value of property title.

Title of the form.

Note: The title is rendered with a theme-dependent default level. As the SmartForm control cannot know the structure of the page, this might not fit the page structure. In this case provide the title using a Title control and set its level to the required value. Add this title to a Toolbar control and assign it to the SmartForm using the customToolbar aggregation.

getUseHorizontalLayout

Gets current value of property useHorizontalLayout.

Specifies whether the groups are rendered in a ResponsiveLayout with the label above the field. Each group is rendered in a new line.

Note: This property should no longer be used. To arrange the fields in columns, ColumnLayout should be used in the layout aggregation.

Note: The value of this property will be passed on to the useHorizontalLayout property of all Group and GroupElement elements.

Since 1.86 replaced by {@link sap.ui.comp.smartform.ColumnLayout ColumnLayout} in the <code>layout</code> aggregation.

getValidationMode

Gets current value of property validationMode.

Controls the SmartForm validation mode. The default mode handles only nested SmartField controls with synchronous validation. If the SmartForm should also handle controls with asynchronous validation the property should be set to Async mode which is the recommended mode to be used as all types of nested fields validation are handled.

Note: Using Async mode the method check will return a promise instead of an array.

Note: Using Async mode the event checked will be called asynchronously when all the nested SmartField validations are executed.

Default value is Standard.

getVisibleProperties

Returns the array of properties currently visible on the UI.

indexOfGroup

Checks for the provided sap.ui.comp.smartform.Group in the aggregation groups. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oGroup sap.ui.comp.smartform.Group

The group whose index is looked for

insertCustomData

Inserts some customData into the aggregation customData.

Note: customData that is used by the SmartField control itself is also added to the Group elements, GroupElement elements and the SmartField controls in the children hierarchy. Additional customData that is not used by the SmartField control internally might not be added.

Param Type DefaultValue Description
oCustomData sap.ui.core.CustomData

the customData to insert; if empty, nothing is inserted

iIndex int

the 0-based index the customData should be inserted at; for a negative value of iIndex, the customData is inserted at position 0; for a value greater than the current size of the aggregation, the customData is inserted at the last position

insertGroup

Inserts a group into the aggregation groups.

Param Type DefaultValue Description
oGroup sap.ui.comp.smartform.Group

The group to insert; if empty, nothing is inserted

iIndex int

The 0-based index the group should be inserted at; for a negative value of iIndex, the group is inserted at position 0; for a value greater than the current size of the aggregation, the group is inserted at the last position

propagateGridDataSpan

Sets default span for GridData layout of group elements when used with horizontal layout.

Note: There is no need to call this function as the update of all GroupElement elements inside the SmartForm control is triggered automatically if the GridDataSpan property of the Layout aggregation changes or the Layout aggregation is added.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllGroups

Removes all the controls from the aggregation groups.

Additionally, it unregisters them from the hosting UIArea.

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

removeGroup

Removes a group from the aggregation groups.

Param Type DefaultValue Description
vGroup int string sap.ui.comp.smartform.Group

The group to remove or its index or id

setCheckButton

Sets a new value for property checkButton.

Specifies whether a check button is added to the toolbar.

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
bCheckButton boolean false

New value for property checkButton

setCustomToolbar

Sets the aggregated customToolbar.

Param Type DefaultValue Description
oCustomToolbar sap.m.Toolbar

The customToolbar to set

setEditable

Sets a new value for property editable.

Applies a device-specific and theme-specific line height and label alignment to the form rows if the form has editable content. If set, all (not only the editable) rows of the form will get the line height of editable fields.

The labels inside the form will be rendered by default in the according mode.

Note: The setting of this property will be passed to all SmartField controls inside the form, so they will be editable if the form is editable.

Warning: The setting of this property will not be passed to controls other than SmartField. For example, Input controls in a form with editable set to false are still editable.

If controls other than SmartField controls are used, and the edit mode of their control is not set correctly, this might lead to visual issues. The labels and fields might be misaligned, the labels might be rendered in the wrong mode, and the spacing between the single controls might be wrong. Also, controls that do not fit the mode might be rendered incorrectly.

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
bEditable boolean false

New value for property editable

setEditTogglable

Sets a new value for property editTogglable.

If set to true, a button to toggle the editable property is shown in the toolbar.

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
bEditTogglable boolean false

New value for property editTogglable

setEntityType

Sets a new value for property entityType.

CSV of entity types for which the flexibility features are available.
For more information about SAPUI5 flexibility, refer to the Developer Guide.
Note: No validation is done. Please ensure that you do not add spaces or special characters.

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

Param Type DefaultValue Description
sEntityType string

New value for property entityType

setExpandable

Sets a new value for property expandable.

Specifies whether the control is expandable. Per default the control is not rendered as expanded.

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
bExpandable boolean false

New value for property expandable

setExpanded

Sets a new value for property expanded.

If expandable, this property indicates whether the state is expanded or not. If expanded, then the toolbar (if available) and the content is rendered; if expanded is false, then only the headerText/headerToolbar is rendered.

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

Param Type DefaultValue Description
bExpanded boolean

New value for property expanded

setFlexEnabled

Sets a new value for property flexEnabled.

Specifies whether the form enables flexibility features, such as adding new fields.
For more information about SAPUI5 flexibility, refer to the Developer Guide.

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
bFlexEnabled boolean true

New value for property flexEnabled

setFocusOnEditableControl

Sets the focus on the first editable control.

setHorizontalLayoutGroupElementMinWidth

Sets a new value for property horizontalLayoutGroupElementMinWidth.

Specifies the minimal size in pixels of all group elements of the form if the horizontal layout is used.

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

Since 1.48.0 please do not use this property as it does not have any effect on the current layout of the <code>SmartForm</code> control.
Param Type DefaultValue Description
iHorizontalLayoutGroupElementMinWidth int

New value for property horizontalLayoutGroupElementMinWidth

setIgnoredFields

Sets a new value for property ignoredFields.

CSV of fields that must be ignored in the OData metadata by the SmartForm control.
Note:
No validation is done. Please ensure that you do not add spaces or special characters.

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

Param Type DefaultValue Description
sIgnoredFields string

New value for property ignoredFields

setImportance

Sets a new value for property importance.

Specifies which smart fields will be visible inside the SmartForm.

If set to high, only smart fields with high importance will be visible.

If set to medium, only smart fields with high and medium importance will be visible.

If set to low (default), all the smart fields will be visible regardless of their importance.

Note: If a smart field is annotated as mandatory or hidden, its visibility will not be affected by the importance property.

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

Default value is Low.

Param Type DefaultValue Description
sImportance sap.ui.comp.smartform.Importance Low

New value for property importance

setLayout

Sets the aggregated layout.

Param Type DefaultValue Description
oLayout sap.ui.comp.smartform.SmartFormLayout

The layout to set

setSemanticObjectController

Sets the aggregated semanticObjectController.

Param Type DefaultValue Description
oSemanticObjectController sap.ui.comp.navpopover.SemanticObjectController

The semanticObjectController to set

setTitle

Sets a new value for property title.

Title of the form.

Note: The title is rendered with a theme-dependent default level. As the SmartForm control cannot know the structure of the page, this might not fit the page structure. In this case provide the title using a Title control and set its level to the required value. Add this title to a Toolbar control and assign it to the SmartForm using the customToolbar aggregation.

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

Param Type DefaultValue Description
sTitle string

New value for property title

setUseHorizontalLayout

Sets a new value for property useHorizontalLayout.

Specifies whether the groups are rendered in a ResponsiveLayout with the label above the field. Each group is rendered in a new line.

Note: This property should no longer be used. To arrange the fields in columns, ColumnLayout should be used in the layout aggregation.

Note: The value of this property will be passed on to the useHorizontalLayout property of all Group and GroupElement elements.

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

Since 1.86 replaced by {@link sap.ui.comp.smartform.ColumnLayout ColumnLayout} in the <code>layout</code> aggregation.
Param Type DefaultValue Description
bUseHorizontalLayout boolean

New value for property useHorizontalLayout

setValidationMode

Sets a new value for property validationMode.

Controls the SmartForm validation mode. The default mode handles only nested SmartField controls with synchronous validation. If the SmartForm should also handle controls with asynchronous validation the property should be set to Async mode which is the recommended mode to be used as all types of nested fields validation are handled.

Note: Using Async mode the method check will return a promise instead of an array.

Note: Using Async mode the event checked will be called asynchronously when all the nested SmartField validations are executed.

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

Default value is Standard.

Param Type DefaultValue Description
sValidationMode sap.ui.comp.smartform.SmartFormValidationMode Standard

New value for property validationMode