class sap.ui.layout.form.ColumnLayout

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

The ColumnLayout control renders a Form control in a column-based responsive way. Depending on its size, the Form control is divided into one or more columns. (XL - max. 4 columns, L - max. 3 columns, M - max. 2 columns and S - 1 column.)

The FormContainer elements are spread out to the columns depending on the number of FormContainer elements and their size. For example, if there are 4 columns and 2 FormContainer elements, each FormContainer element will use 2 columns. If there are 3 columns and 2 FormContainer elements, the larger one will use 2 columns, the smaller one 1 column. The size of a FormContainer element will be determined based on the number of visible FormElement elements assigned to it. If there are more FormContainer elements than columns, every FormContainer element uses only one column. So the last row of the Form control will not be fully used.

The default size of the FormContainer element can be overwritten by using ColumnContainerData as LayoutData. If one FormContainer element has ColumnContainerData set, the size calculation of the other FormContainer elements might not lead to the expected result. In this case, use ColumnContainerData also for the other FormContainer elements.

The FormElement elements are spread out to the columns of a FormContainer element arranged in a newspaper-like order. The position of the labels and fields depends on the size of the used column. If there is enough space, the labels are beside the fields, otherwise above the fields.

The default size of a content control of a FormElement element can be overwritten using ColumnElementData as LayoutData. If one control assigned to a FormElement element has ColumnElementData set, the size calculation of the other controls assigned to the FormElement element might not lead to the expected result. In this case, use ColumnElementData for the other controls, assigned to the FormElement element, too.

The placement of the FormElement elements is made by the browser column-count logic. So this can be different in different browsers and lead in some cases to other results than might be expected.

Note: This control cannot be used stand-alone, it just renders a Form control, so it must be assigned to a Form control using the layout aggregation.


Constructor

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

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.ColumnLayout(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
columnsL sap.ui.layout.form.ColumnsL 2

Number of columns for large size.

The number of columns for large size must not be smaller than the number of columns for medium size.

Visibility: public
columnsM sap.ui.layout.form.ColumnsM 1

Number of columns for medium size.

Visibility: public
columnsXL sap.ui.layout.form.ColumnsXL 2

Number of columns for extra-large size.

The number of columns for extra-large size must not be smaller than the number of columns for large size.

Visibility: public
emptyCellsLarge sap.ui.layout.form.EmptyCells 0

Defines how many cells are empty at the end of a row. This could be used to keep the fields small on large screens.

Visibility: public
labelCellsLarge sap.ui.layout.form.ColumnCells 4

Defines how many cells a label uses if the column is large.

Visibility: public

Borrowed Properties

Name Type Default Value Description
backgroundDesign sap.ui.layout.BackgroundDesign Translucent

Specifies the background color of the Form content.

Note: The visualization of the different options depends on the theme used.

Since: 1.36.0.

Visibility: public

Methods Overview

Method Description
sap.ui.layout.form.ColumnLayout.extend

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

getColumnsL

Gets current value of property columnsL.

Number of columns for large size.

The number of columns for large size must not be smaller than the number of columns for medium size.

Default value is 2.

getColumnsM

Gets current value of property columnsM.

Number of columns for medium size.

Default value is 1.

getColumnsXL

Gets current value of property columnsXL.

Number of columns for extra-large size.

The number of columns for extra-large size must not be smaller than the number of columns for large size.

Default value is 2.

getEmptyCellsLarge

Gets current value of property emptyCellsLarge.

Defines how many cells are empty at the end of a row. This could be used to keep the fields small on large screens.

Default value is 0.

getLabelCellsLarge

Gets current value of property labelCellsLarge.

Defines how many cells a label uses if the column is large.

Default value is 4.

sap.ui.layout.form.ColumnLayout.getMetadata

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

setColumnsL

Sets a new value for property columnsL.

Number of columns for large size.

The number of columns for large size must not be smaller than the number of columns for medium size.

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

Default value is 2.

setColumnsM

Sets a new value for property columnsM.

Number of columns for medium size.

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

Default value is 1.

setColumnsXL

Sets a new value for property columnsXL.

Number of columns for extra-large size.

The number of columns for extra-large size must not be smaller than the number of columns for large size.

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

Default value is 2.

setEmptyCellsLarge

Sets a new value for property emptyCellsLarge.

Defines how many cells are empty at the end of a row. This could be used to keep the fields small on large screens.

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

Default value is 0.

setLabelCellsLarge

Sets a new value for property labelCellsLarge.

Defines how many cells a label uses if the column is large.

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

Default value is 4.

sap.ui.layout.form.ColumnLayout.extend

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

getColumnsL

Gets current value of property columnsL.

Number of columns for large size.

The number of columns for large size must not be smaller than the number of columns for medium size.

Default value is 2.

getColumnsM

Gets current value of property columnsM.

Number of columns for medium size.

Default value is 1.

getColumnsXL

Gets current value of property columnsXL.

Number of columns for extra-large size.

The number of columns for extra-large size must not be smaller than the number of columns for large size.

Default value is 2.

getEmptyCellsLarge

Gets current value of property emptyCellsLarge.

Defines how many cells are empty at the end of a row. This could be used to keep the fields small on large screens.

Default value is 0.

getLabelCellsLarge

Gets current value of property labelCellsLarge.

Defines how many cells a label uses if the column is large.

Default value is 4.

sap.ui.layout.form.ColumnLayout.getMetadata

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

setColumnsL

Sets a new value for property columnsL.

Number of columns for large size.

The number of columns for large size must not be smaller than the number of columns for medium size.

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

Default value is 2.

Param Type DefaultValue Description
sColumnsL sap.ui.layout.form.ColumnsL 2

New value for property columnsL

setColumnsM

Sets a new value for property columnsM.

Number of columns for medium size.

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

Default value is 1.

Param Type DefaultValue Description
sColumnsM sap.ui.layout.form.ColumnsM 1

New value for property columnsM

setColumnsXL

Sets a new value for property columnsXL.

Number of columns for extra-large size.

The number of columns for extra-large size must not be smaller than the number of columns for large size.

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

Default value is 2.

Param Type DefaultValue Description
sColumnsXL sap.ui.layout.form.ColumnsXL 2

New value for property columnsXL

setEmptyCellsLarge

Sets a new value for property emptyCellsLarge.

Defines how many cells are empty at the end of a row. This could be used to keep the fields small on large screens.

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

Default value is 0.

Param Type DefaultValue Description
sEmptyCellsLarge sap.ui.layout.form.EmptyCells 0

New value for property emptyCellsLarge

setLabelCellsLarge

Sets a new value for property labelCellsLarge.

Defines how many cells a label uses if the column is large.

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

Default value is 4.

Param Type DefaultValue Description
sLabelCellsLarge sap.ui.layout.form.ColumnCells 4

New value for property labelCellsLarge