A list-based control with grid layout capabilities.
The control is based on sap.m.ListBase and adds the flexibility to configure different grid layouts. The layout used is based on the CSS display grid and the control has a default configuration.
With customLayout
aggregation it is possible to use:
Every item can override its size by specifying the number of columns and/or rows it will take in the grid. This is done using GridItemLayoutData.
For best visualization, items of type sap.f.GridListItem should be used inside the items
aggregation.
For general cases, use the default grid configuration of the GridList
. For Box case (equal sized items), use customLayout
aggregation with GridBoxLayout For Grids which need different configurations based on available width, use customLayout
aggregation with GridResponsiveLayout To set a specific position to an item or define its dimensions in the grid, pass layoutData
of type GridItemLayoutData
When to use
When not to use
Drag and drop is enabled for the GridList
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.
GridList
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 GridList
, 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 GridList
using the method #focusItemByDirection.
Documentation links:
Constructor for a new GridList.
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.GridList(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 |
Default Aggregation:
Name | Cardinality | Type | Description |
---|---|---|---|
customLayout | 0..1 | sap.ui.layout.cssgrid.GridLayoutBase |
Defines a custom grid layout |
Event | Description |
---|---|
borderReached |
Fires if the border of the visualizations is reached so that an application can react on this. |
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 the column index, from which the border is reached. |
Method | Description |
---|---|
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. |
destroyCustomLayout |
Destroys the customLayout in the aggregation customLayout. |
detachBorderReached |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
sap.f.GridList.extend |
Creates a new subclass of class sap.f.GridList with name
|
fireBorderReached |
Fires event borderReached to attached listeners. |
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 |
getCustomLayout |
Gets content of aggregation customLayout. Defines a custom grid layout |
getGridDomRefs |
Implements IGridConfigurable interface. |
getGridLayoutConfiguration |
Implements IGridConfigurable interface. |
sap.f.GridList.getMetadata |
Returns a metadata object for class sap.f.GridList. |
getNavigationMatrix | |
onItemNavigationBorderReached |
Fires when border of the |
setCustomLayout |
Sets the aggregated customLayout. |
Attaches event handler fnFunction
to the borderReached event of this sap.f.GridList
.
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.GridList
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 |
Detaches event handler fnFunction
from the borderReached event of this sap.f.GridList
.
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.GridList with name sClassName
and enriches it with the information contained in oClassInfo
.
oClassInfo
might contain the same kind of information as described in sap.m.ListBase.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 the column index, from which the border is reached. |
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 GridList
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. |
Sets the aggregated customLayout.
Param | Type | DefaultValue | Description |
---|---|---|---|
oCustomLayout | sap.ui.layout.cssgrid.GridLayoutBase |
The customLayout to set |