A layout container control used for aligning items with various sizes in a simple grid.
The control is used to align tiles, cards and other controls in configuration, such as a home page or a dashboard. It represents a grid layout with specific row and column sizes, in which the items can take any number of rows and columns.
The number of columns and rows each item takes can be configured with the use of the sap.f.GridContainerItemLayoutData
.
All rows have the same height and all columns have the same width. Their sizes can be configured with the use of the layout
aggregation and sap.f.GridContainerSettings
.
When to use
When not to use
<f:GridContainer> <f:layout> <f:GridContainerSettings rowSize="5rem" columnSize="5rem" gap="1rem" /> </f:layout> <f:layoutS> <f:GridContainerSettings rowSize="4rem" columnSize="4rem" gap="0.5rem" /> </f:layoutS> <f:items> <GenericTile header="Sales Fulfillment"> <layoutData> <f:GridContainerItemLayoutData rows="2" columns="2" /> </layoutData> </GenericTile> <w:Card manifest="url-to-manifest"> <w:layoutData> <f:GridContainerItemLayoutData rows="6" columns="3" /> </w:layoutData> </w:Card> <Panel> <layoutData> <f:GridContainerItemLayoutData columns="4" /> </layoutData> <Text text="Sales information" /> </Panel> </f:items> </f:GridContainer>
Drag and drop is enabled for the GridContainer
with enhanced visualization and interaction, better suited for grid items. This is configured by using the sap.f.dnd.GridDropInfo
.
Similar to the sap.ui.core.dnd.DropInfo
, sap.f.dnd.GridDropInfo
has to be added to the dragDropConfig
aggregation, by using sap.ui.core.Element#addDragDropConfig
.
Both sap.ui.core.dnd.DropInfo
and sap.f.dnd.GridDropInfo
can be used to configure drag and drop. The difference is that the sap.f.dnd.GridDropInfo
will provide a drop indicator, which mimics the size of the dragged item and shows the potential drop position inside the grid.
GridContainer
provides support for two-dimensional keyboard navigation through its contained controls. Navigating up/down or left/right using the arrow keys follows the configurable two-dimensional grid mesh. This provides stable navigation paths in the cases when there are items of different sizes. When the user presses an arrow key in a direction outward of the GridContainer
, a borderReached
event will be fired. The implementation of the borderReached
event allows the application developer to control where the focus goes, and depending on the surrounding layout pass the focus to a specific place in a neighboring GridContainer
using the method #focusItemByDirection.
Documentation links:
Constructor for a new sap.f.GridContainer
.
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.f.GridContainer(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 |
---|---|---|---|
allowDenseFill | boolean | false | Increases the density when arranging the items. Smaller items will take up all of the available space, ignoring their order. Note: The order of the items is ignored. An item which is normally at the bottom, can appear on top. Visibility: public |
containerQuery | boolean | false | If set to |
inlineBlockLayout | boolean | false | Makes the grid items act like an inline-block elements. They will be arranged in rows with height equal to the highest item in the row. Note: If set to |
minHeight | sap.ui.core.CSSSize | 2rem | Defines the minimum height of the grid. Allows an empty grid to be available as a drop target. Visibility: public |
snapToRow | boolean | false | Should the items stretch to fill the rows that they occupy, or not. If set to |
width | sap.ui.core.CSSSize | empty string | Defines the width of the control. Visibility: public |
Default Aggregation: items
Name | Cardinality | Type | Description |
---|---|---|---|
_defaultLayout | 0..1 | sap.f.GridContainerSettings |
Default sap.f.GridContainerSettings |
items (default) | 0..n | sap.ui.core.Control |
The items contained by the control. |
layout | 0..1 | sap.f.GridContainerSettings |
The sap.f.GridContainerSettings applied if no settings are provided for a specific size. If no layout is given, a default layout will be used. See the default values for Note: It is not possible to reuse the same instance of |
layoutL | 0..1 | sap.f.GridContainerSettings |
The sap.f.GridContainerSettings applied for size "L". Range: 1023px - 1439px. |
layoutM | 0..1 | sap.f.GridContainerSettings |
The sap.f.GridContainerSettings applied for size "M". Range: 600px - 1023px. |
layoutS | 0..1 | sap.f.GridContainerSettings |
The sap.f.GridContainerSettings applied for size "S". Range: 375px - 599px. |
layoutXL | 0..1 | sap.f.GridContainerSettings |
The sap.f.GridContainerSettings applied for size "XL". Range: from 1440px. |
layoutXS | 0..1 | sap.f.GridContainerSettings |
The sap.f.GridContainerSettings applied for size "XS". Range: up to 374px. |
Event | Description |
---|---|
borderReached |
Fires if the border of the visualizations is reached so that an application can react on this. |
columnsChange |
Fired when the grid columns count is changed. |
layoutChange |
Fired when the currently active GridSettings change. |
Fires if the border of the visualizations is reached so that an application can react on this.
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
event | jQuery.Event |
Event that leads to the focus change. |
direction | sap.f.NavigationDirection |
The navigation direction that is used to reach the border. |
row | int |
The row index, from which the border is reached. |
column | int |
The column index, from which the border is reached. |
Method | Description |
---|---|
addItem |
Adds some item to the aggregation items. |
attachBorderReached |
Attaches event handler When called, the context of the event handler (its Fires if the border of the visualizations is reached so that an application can react on this. |
attachColumnsChange |
Attaches event handler When called, the context of the event handler (its Fired when the grid columns count is changed. |
attachLayoutChange |
Attaches event handler When called, the context of the event handler (its Fired when the currently active GridSettings change. |
destroyItems |
Destroys all the items in the aggregation items. |
destroyLayout |
Destroys the layout in the aggregation layout. |
destroyLayoutL |
Destroys the layoutL in the aggregation layoutL. |
destroyLayoutM |
Destroys the layoutM in the aggregation layoutM. |
destroyLayoutS |
Destroys the layoutS in the aggregation layoutS. |
destroyLayoutXL |
Destroys the layoutXL in the aggregation layoutXL. |
destroyLayoutXS |
Destroys the layoutXS in the aggregation layoutXS. |
detachBorderReached |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachColumnsChange |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachLayoutChange |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
sap.f.GridContainer.extend |
Creates a new subclass of class sap.f.GridContainer with name
|
fireBorderReached |
Fires event borderReached to attached listeners. |
fireColumnsChange |
Fires event columnsChange to attached listeners. |
fireLayoutChange |
Fires event layoutChange to attached listeners. |
focusItem |
Focuses the item on the given index. Should be called after successful drop operation. Note:Should not be called before the |
focusItemByDirection |
Focuses an item in the given direction - up, down, left or right, from the starting position specified by row and column. If the direction is up or down, the method focuses the nearest item in the same column, located in the specified direction. If the direction is left or right, the method focuses the nearest item at the same row, in the specified direction. Note:Should be called after the rendering of |
getActiveLayoutSettings |
Gets the |
getAllowDenseFill |
Gets current value of property allowDenseFill. Increases the density when arranging the items. Smaller items will take up all of the available space, ignoring their order. Note: The order of the items is ignored. An item which is normally at the bottom, can appear on top. Default value is |
getContainerQuery |
Gets current value of property containerQuery. If set to Default value is |
getInlineBlockLayout |
Gets current value of property inlineBlockLayout. Makes the grid items act like an inline-block elements. They will be arranged in rows with height equal to the highest item in the row. Note: If set to Default value is |
getItems |
Gets content of aggregation items. The items contained by the control. |
getLayout |
Gets content of aggregation layout. The sap.f.GridContainerSettings applied if no settings are provided for a specific size. If no layout is given, a default layout will be used. See the default values for Note: It is not possible to reuse the same instance of |
getLayoutL |
Gets content of aggregation layoutL. The sap.f.GridContainerSettings applied for size "L". Range: 1023px - 1439px. |
getLayoutM |
Gets content of aggregation layoutM. The sap.f.GridContainerSettings applied for size "M". Range: 600px - 1023px. |
getLayoutS |
Gets content of aggregation layoutS. The sap.f.GridContainerSettings applied for size "S". Range: 375px - 599px. |
getLayoutXL |
Gets content of aggregation layoutXL. The sap.f.GridContainerSettings applied for size "XL". Range: from 1440px. |
getLayoutXS |
Gets content of aggregation layoutXS. The sap.f.GridContainerSettings applied for size "XS". Range: up to 374px. |
sap.f.GridContainer.getMetadata |
Returns a metadata object for class sap.f.GridContainer. |
getMinHeight |
Gets current value of property minHeight. Defines the minimum height of the grid. Allows an empty grid to be available as a drop target. Default value is |
getNavigationMatrix | |
getSnapToRow |
Gets current value of property snapToRow. Should the items stretch to fill the rows that they occupy, or not. If set to Default value is |
getWidth |
Gets current value of property width. Defines the width of the control. Default value is |
indexOfItem |
Checks for the provided |
insertItem |
Inserts an item into the aggregation named |
onItemNavigationBorderReached |
Fires when border of the |
removeAllItems |
Removes all the controls from the aggregation items. Additionally, it unregisters them from the hosting UIArea. |
removeItem |
Removes an item from the aggregation named |
setAllowDenseFill |
Sets a new value for property allowDenseFill. Increases the density when arranging the items. Smaller items will take up all of the available space, ignoring their order. Note: The order of the items is ignored. An item which is normally at the bottom, can appear on top. When called with a value of Default value is |
setContainerQuery |
Sets a new value for property containerQuery. If set to When called with a value of Default value is |
setInlineBlockLayout |
Sets a new value for property inlineBlockLayout. Makes the grid items act like an inline-block elements. They will be arranged in rows with height equal to the highest item in the row. Note: If set to When called with a value of Default value is |
setLayout |
Sets the aggregated layout. |
setLayoutL |
Sets the aggregated layoutL. |
setLayoutM |
Sets the aggregated layoutM. |
setLayoutS |
Sets the aggregated layoutS. |
setLayoutXL |
Sets the aggregated layoutXL. |
setLayoutXS |
Sets the aggregated layoutXS. |
setMinHeight |
Sets a new value for property minHeight. Defines the minimum height of the grid. Allows an empty grid to be available as a drop target. When called with a value of Default value is |
setSnapToRow |
Sets a new value for property snapToRow. Should the items stretch to fill the rows that they occupy, or not. If set to When called with a value of Default value is |
setWidth |
Sets a new value for property width. Defines the width of the control. When called with a value of Default value is |
Adds some item to the aggregation items.
Param | Type | DefaultValue | Description |
---|---|---|---|
oItem | sap.ui.core.Control |
The item to add; if empty, nothing is inserted |
Attaches event handler fnFunction
to the borderReached event of this sap.f.GridContainer
.
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.f.GridContainer
itself.
Fires if the border of the visualizations is reached so that an application can react on this.
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 |
Attaches event handler fnFunction
to the columnsChange event of this sap.f.GridContainer
.
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.f.GridContainer
itself.
Fired when the grid columns count is changed.
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 |
Attaches event handler fnFunction
to the layoutChange event of this sap.f.GridContainer
.
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.f.GridContainer
itself.
Fired when the currently active GridSettings change.
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 |
Detaches event handler fnFunction
from the borderReached event of this sap.f.GridContainer
.
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 |
Detaches event handler fnFunction
from the columnsChange event of this sap.f.GridContainer
.
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 |
Detaches event handler fnFunction
from the layoutChange event of this sap.f.GridContainer
.
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 |
Creates a new subclass of class sap.f.GridContainer 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 |
Fires event borderReached to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
event | jQuery.Event |
Event that leads to the focus change. |
|
direction | sap.f.NavigationDirection |
The navigation direction that is used to reach the border. |
|
row | int |
The row index, from which the border is reached. |
|
column | int |
The column index, from which the border is reached. |
Fires event columnsChange to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
columns | int |
The count of the gird columns. |
Fires event layoutChange to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
layout | string |
The name of the newly active layout. |
Focuses the item on the given index. Should be called after successful drop operation.
Note:Should not be called before the GridContainer
has been rendered.
Param | Type | DefaultValue | Description |
---|---|---|---|
iIndex | int |
The index of the item, which will be focused. |
Focuses an item in the given direction - up, down, left or right, from the starting position specified by row and column.
If the direction is up or down, the method focuses the nearest item in the same column, located in the specified direction.
If the direction is left or right, the method focuses the nearest item at the same row, in the specified direction.
Note:Should be called after the rendering of GridContainer
is ready.
Param | Type | DefaultValue | Description |
---|---|---|---|
sDirection | sap.f.NavigationDirection |
The navigation direction. |
|
iRow | int |
The row index of the starting position. |
|
iColumn | int |
The column index of the starting position. |
Gets current value of property allowDenseFill.
Increases the density when arranging the items. Smaller items will take up all of the available space, ignoring their order.
Note: The order of the items is ignored. An item which is normally at the bottom, can appear on top.
Default value is false
.
Gets current value of property containerQuery.
If set to true
the current range (large, medium or small) is defined by the size of the container surrounding the GridContainer
, instead of the device screen size (media Query).
Default value is false
.
Gets current value of property inlineBlockLayout.
Makes the grid items act like an inline-block elements. They will be arranged in rows with height equal to the highest item in the row.
Note: If set to true
the properties rowSize
for grid layout, and minRows
and rows
per item will be ignored.
Default value is false
.
Gets content of aggregation layout.
The sap.f.GridContainerSettings applied if no settings are provided for a specific size.
If no layout is given, a default layout will be used. See the default values for sap.f.GridContainerSettings
.
Note: It is not possible to reuse the same instance of GridContainerSettings
for several layouts. New instance has to be created for each of them. This is caused by the fact that one object can exist in only a single aggregation.
Gets content of aggregation layoutL.
The sap.f.GridContainerSettings applied for size "L". Range: 1023px - 1439px.
Gets content of aggregation layoutM.
The sap.f.GridContainerSettings applied for size "M". Range: 600px - 1023px.
Gets content of aggregation layoutS.
The sap.f.GridContainerSettings applied for size "S". Range: 375px - 599px.
Gets content of aggregation layoutXL.
The sap.f.GridContainerSettings applied for size "XL". Range: from 1440px.
Gets content of aggregation layoutXS.
The sap.f.GridContainerSettings applied for size "XS". Range: up to 374px.
Gets current value of property minHeight.
Defines the minimum height of the grid.
Allows an empty grid to be available as a drop target.
Default value is "2rem"
.
Gets current value of property snapToRow.
Should the items stretch to fill the rows that they occupy, or not.
If set to true
the items will stretch.
Default value is false
.
Gets current value of property width.
Defines the width of the control.
Default value is empty string
.
Checks for the provided sap.ui.core.Control
in the aggregation items. and returns its index if found or -1 otherwise.
Param | Type | DefaultValue | Description |
---|---|---|---|
oItem | sap.ui.core.Control |
The item whose index is looked for |
Inserts an item into the aggregation named items
.
Param | Type | DefaultValue | Description |
---|---|---|---|
oItem | sap.ui.core.Item |
The item to be inserted; if empty, nothing is inserted. |
|
iIndex | int |
The |
Removes all the controls from the aggregation items.
Additionally, it unregisters them from the hosting UIArea.
Removes an item from the aggregation named items
.
Param | Type | DefaultValue | Description |
---|---|---|---|
vItem | int string sap.ui.core.Item |
The item to remove or its index or ID. |
Sets a new value for property allowDenseFill.
Increases the density when arranging the items. Smaller items will take up all of the available space, ignoring their order.
Note: The order of the items is ignored. An item which is normally at the bottom, can appear on top.
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 |
---|---|---|---|
bAllowDenseFill | boolean | false |
New value for property |
Sets a new value for property containerQuery.
If set to true
the current range (large, medium or small) is defined by the size of the container surrounding the GridContainer
, instead of the device screen size (media Query).
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 |
---|---|---|---|
bContainerQuery | boolean | false |
New value for property |
Sets a new value for property inlineBlockLayout.
Makes the grid items act like an inline-block elements. They will be arranged in rows with height equal to the highest item in the row.
Note: If set to true
the properties rowSize
for grid layout, and minRows
and rows
per item will be ignored.
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 |
---|---|---|---|
bInlineBlockLayout | boolean | false |
New value for property |
Sets the aggregated layout.
Param | Type | DefaultValue | Description |
---|---|---|---|
oLayout | sap.f.GridContainerSettings |
The layout to set |
Sets the aggregated layoutL.
Param | Type | DefaultValue | Description |
---|---|---|---|
oLayoutL | sap.f.GridContainerSettings |
The layoutL to set |
Sets the aggregated layoutM.
Param | Type | DefaultValue | Description |
---|---|---|---|
oLayoutM | sap.f.GridContainerSettings |
The layoutM to set |
Sets the aggregated layoutS.
Param | Type | DefaultValue | Description |
---|---|---|---|
oLayoutS | sap.f.GridContainerSettings |
The layoutS to set |
Sets the aggregated layoutXL.
Param | Type | DefaultValue | Description |
---|---|---|---|
oLayoutXL | sap.f.GridContainerSettings |
The layoutXL to set |
Sets the aggregated layoutXS.
Param | Type | DefaultValue | Description |
---|---|---|---|
oLayoutXS | sap.f.GridContainerSettings |
The layoutXS to set |
Sets a new value for property minHeight.
Defines the minimum height of the grid.
Allows an empty grid to be available as a drop target.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is "2rem"
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sMinHeight | sap.ui.core.CSSSize | "2rem" |
New value for property |
Sets a new value for property snapToRow.
Should the items stretch to fill the rows that they occupy, or not.
If set to true
the items will stretch.
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 |
---|---|---|---|
bSnapToRow | boolean | false |
New value for property |
Sets a new value for property width.
Defines the width of the control.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is empty string
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sWidth | sap.ui.core.CSSSize | "" |
New value for property |