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 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 |
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, 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. |
width | sap.ui.core.CSSSize | Width of the |
Default Aggregation: formContainers
Name | Cardinality | Type | Description |
---|---|---|---|
formContainers (default) | 0..n | sap.ui.layout.form.FormContainer |
Containers with the content of the form. A |
layout | 0..1 | sap.ui.layout.form.FormLayout |
Layout of the |
title | 0..1 | sap.ui.core.Title |
Title of the Note: If a Note: If the title is provided as a string, the title is rendered with a theme-dependent default level. As the |
toolbar | 0..1 | sap.ui.core.Toolbar |
Toolbar of the Note: If a |
Name | Cardinality | Type | Description |
---|---|---|---|
ariaLabelledBy | 0..n | sap.ui.core.Control |
Association to controls / IDs that label this control (see WAI-ARIA attribute |
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
|
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, 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 |
getFormContainers |
Gets content of aggregation formContainers. Containers with the content of the form. A |
getLayout |
Gets content of aggregation layout. Layout of the |
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 Note: If a Note: If the title is provided as a string, the title is rendered with a theme-dependent default level. As the |
getToolbar |
Gets content of aggregation toolbar. Toolbar of the Note: If a |
getWidth |
Gets current value of property width. Width of the |
indexOfFormContainer |
Checks for the provided |
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, 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 Default value is |
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 When called with a value of |
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 |
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 |
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 |
Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
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
.
Gets content of aggregation formContainers.
Containers with the content of the form. A FormContainer
represents a group inside the Form
.
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.
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.
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.
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 |
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 |
Removes all the controls from the aggregation formContainers.
Additionally, it unregisters them from the hosting UIArea.
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 |
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 |
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 |
Sets the aggregated layout.
Param | Type | DefaultValue | Description |
---|---|---|---|
oLayout | sap.ui.layout.form.FormLayout |
The layout to set |
Sets the aggregated title.
Param | Type | DefaultValue | Description |
---|---|---|---|
vTitle | sap.ui.core.Title string |
The title to set |
Sets the aggregated toolbar.
Param | Type | DefaultValue | Description |
---|---|---|---|
oToolbar | sap.ui.core.Toolbar |
The toolbar to set |
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 |