class sap.ui.layout.form.Form

Control sample: sap.ui.layout.form.Form
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/layout/form/Form
Application Component: CA-UI5-CMP

A Form control arranges labels and fields (like input fields) into groups and rows. There are different ways to visualize forms for different screen sizes.

A Form is structured into FormContainers. Each FormContainer consists of FormElements. The FormElements consists of a label and the form fields. A Form doesn't render its content by itself. The rendering is done by the assigned FormLayout. This is so that the rendering can be adopted to new UI requirements without changing the Form itself.

For the content of a Form, VariantLayoutData are supported to allow simple switching of the FormLayout. LayoutData on the content can be used to overwrite the default layout of the Form.

The Form (and its sub-controls) automatically add label and field assignment to enable screen reader support. It also adds keyboard support to navigate between the fields and groups inside the form.

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

If editable controls are used as content, the editable property must be set to true, otherwise to false. If the editable property is set incorrectly, there will be visual issues like wrong label alignment or wrong spacing between the controls.


Constructor

Constructor for a new sap.ui.layout.form.Form.

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.layout.form.Form(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 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 does not change the content of the form. For example, Input controls in a form with editable set to false are still editable.

Warning: If this property is wrongly set, 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.

Since: 1.20.0.

Visibility: public
width sap.ui.core.CSSSize

Width of the Form.

Visibility: public

Aggregations

Default Aggregation: formContainers

Name Cardinality Type Description
formContainers (default) 0..n sap.ui.layout.form.FormContainer

Containers with the content of the form. A FormContainer represents a group inside the Form.

layout 0..1 sap.ui.layout.form.FormLayout

Layout of the Form. The assigned Layout renders the Form. We recommend using the ColumnLayout for rendering a Form, as its responsiveness allows the available space to be used in the best way possible.

title 0..1 sap.ui.core.Title

Title of the Form. Can either be a Title element or a string. If a Title element it used, the style of the title can be set.

Note: If a Toolbar is used, the Title is ignored.

Note: If the title is provided as a string, the title is rendered with a theme-dependent default level. As the Form control cannot know the structure of the page, this might not fit the page structure. In this case provide the title using a Title element and set its level to the needed value.

toolbar 0..1 sap.ui.core.Toolbar

Toolbar of the Form.

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

Since: 1.36.0.


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.28.0.


Methods Overview

Method Description
addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

addFormContainer

Adds some formContainer to the aggregation formContainers.

destroyFormContainers

Destroys all the formContainers in the aggregation formContainers.

destroyLayout

Destroys the layout in the aggregation layout.

destroyTitle

Destroys the title in the aggregation title.

destroyToolbar

Destroys the toolbar in the aggregation toolbar.

sap.ui.layout.form.Form.extend

Creates a new subclass of class sap.ui.layout.form.Form 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.

getAriaLabelledBy

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

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 does not change the content of the form. For example, Input controls in a form with editable set to false are still editable.

Warning: If this property is wrongly set, 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.

getFormContainers

Gets content of aggregation formContainers.

Containers with the content of the form. A FormContainer represents a group inside the Form.

getLayout

Gets content of aggregation layout.

Layout of the Form. The assigned Layout renders the Form. We recommend using the ColumnLayout for rendering a Form, as its responsiveness allows the available space to be used in the best way possible.

sap.ui.layout.form.Form.getMetadata

Returns a metadata object for class sap.ui.layout.form.Form.

getTitle

Gets content of aggregation title.

Title of the Form. Can either be a Title element or a string. If a Title element it used, the style of the title can be set.

Note: If a Toolbar is used, the Title is ignored.

Note: If the title is provided as a string, the title is rendered with a theme-dependent default level. As the Form control cannot know the structure of the page, this might not fit the page structure. In this case provide the title using a Title element and set its level to the needed value.

getToolbar

Gets content of aggregation toolbar.

Toolbar of the Form.

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

getWidth

Gets current value of property width.

Width of the Form.

indexOfFormContainer

Checks for the provided sap.ui.layout.form.FormContainer in the aggregation formContainers. and returns its index if found or -1 otherwise.

insertFormContainer

Inserts a formContainer into the aggregation formContainers.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllFormContainers

Removes all the controls from the aggregation formContainers.

Additionally, it unregisters them from the hosting UIArea.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

removeFormContainer

Removes a formContainer from the aggregation formContainers.

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 does not change the content of the form. For example, Input controls in a form with editable set to false are still editable.

Warning: If this property is wrongly set, 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.

setLayout

Sets the aggregated layout.

setTitle

Sets the aggregated title.

setToolbar

Sets the aggregated toolbar.

setWidth

Sets a new value for property width.

Width of the Form.

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

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

addFormContainer

Adds some formContainer to the aggregation formContainers.

Param Type DefaultValue Description
oFormContainer sap.ui.layout.form.FormContainer

The formContainer to add; if empty, nothing is inserted

destroyFormContainers

Destroys all the formContainers in the aggregation formContainers.

destroyLayout

Destroys the layout in the aggregation layout.

destroyTitle

Destroys the title in the aggregation title.

destroyToolbar

Destroys the toolbar in the aggregation toolbar.

sap.ui.layout.form.Form.extend

Creates a new subclass of class sap.ui.layout.form.Form 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

getAriaLabelledBy

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

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 does not change the content of the form. For example, Input controls in a form with editable set to false are still editable.

Warning: If this property is wrongly set, 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.

getFormContainers

Gets content of aggregation formContainers.

Containers with the content of the form. A FormContainer represents a group inside the Form.

getLayout

Gets content of aggregation layout.

Layout of the Form. The assigned Layout renders the Form. We recommend using the ColumnLayout for rendering a Form, as its responsiveness allows the available space to be used in the best way possible.

sap.ui.layout.form.Form.getMetadata

Returns a metadata object for class sap.ui.layout.form.Form.

getTitle

Gets content of aggregation title.

Title of the Form. Can either be a Title element or a string. If a Title element it used, the style of the title can be set.

Note: If a Toolbar is used, the Title is ignored.

Note: If the title is provided as a string, the title is rendered with a theme-dependent default level. As the Form control cannot know the structure of the page, this might not fit the page structure. In this case provide the title using a Title element and set its level to the needed value.

getToolbar

Gets content of aggregation toolbar.

Toolbar of the Form.

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

getWidth

Gets current value of property width.

Width of the Form.

indexOfFormContainer

Checks for the provided sap.ui.layout.form.FormContainer in the aggregation formContainers. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oFormContainer sap.ui.layout.form.FormContainer

The formContainer whose index is looked for

insertFormContainer

Inserts a formContainer into the aggregation formContainers.

Param Type DefaultValue Description
oFormContainer sap.ui.layout.form.FormContainer

The formContainer to insert; if empty, nothing is inserted

iIndex int

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

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllFormContainers

Removes all the controls from the aggregation formContainers.

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

removeFormContainer

Removes a formContainer from the aggregation formContainers.

Param Type DefaultValue Description
vFormContainer int string sap.ui.layout.form.FormContainer

The formContainer to remove or its index or id

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 does not change the content of the form. For example, Input controls in a form with editable set to false are still editable.

Warning: If this property is wrongly set, 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

setLayout

Sets the aggregated layout.

Param Type DefaultValue Description
oLayout sap.ui.layout.form.FormLayout

The layout to set

setTitle

Sets the aggregated title.

Param Type DefaultValue Description
vTitle sap.ui.core.Title string

The title to set

setToolbar

Sets the aggregated toolbar.

Param Type DefaultValue Description
oToolbar sap.ui.core.Toolbar

The toolbar to set

setWidth

Sets a new value for property width.

Width of the Form.

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