Layout control that allows additional (side) content to be displayed dynamically.
DynamicSideContent
is a layout control that allows additional content to be displayed in a way that flexibly adapts to different screen sizes. The side content appears in a container next to or directly below the main content (it doesn't overlay). When the side content is triggered, the main content becomes narrower (if appearing side-by-side). The side content contains a separate scrollbar when appearing next to the main content.
When to use?
Use this control if you want to display relevant information that is not critical for users to complete a task. Users should have access to all the key functions and critical information in the app even if they do not see the side content. This is important because on smaller screen sizes it may be difficult to display the side content in a way that is easily accessible for the user.
When not to use?
Don't use it if you want to display navigation or critical information that prevents users from completing a task when they have no access to the side content.
Screen width > 1440 px
Screen width <= 1440 px and > 720px
Screen width <= 720 px (for example on a mobile device)
A special case, allows for comparison mode between the main and side content. In this case, the screen is split into 50:50 percent for main vs. side content. The responsive behavior of the equal split is the same as in the standard view - the side content disappears on screen widths of less than 720 px and can only be viewed by triggering it.
Note: If the control that has property sticky inside the DynamicSideContent
the stickiness of that control will not work. DynamicSideContent
has the overflow: auto style definition and this prevents the sticky elements of the control from becoming fixed at the top of the viewport. This applies for example to sap.m.Table and sap.m.PlanningCalendar.
Constructor for a new DynamicSideContent
.
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.DynamicSideContent(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 |
---|---|---|---|
containerQuery | boolean | false | If set to TRUE, then not the media Query (device screen size) but the size of the container, surrounding the control, defines the current range. Visibility: public |
equalSplit | boolean | false | Defines whether the control is in equal split mode. In this mode, the side and the main content take 50:50 percent of the container on all screen sizes except for phone, where the main and side contents are switching visibility using the toggle method. Visibility: public |
mcSpan | int | 0 | Defiles the main content span size Visibility: hidden |
scSpan | int | 0 | Defines the side content span size Visibility: hidden |
showMainContent | boolean | true | Determines whether the main content is visible or hidden. Visibility: public |
showSideContent | boolean | true | Determines whether the side content is visible or hidden. Note: If both |
sideContentFallDown | sap.ui.layout.SideContentFallDown | OnMinimumWidth | Determines on which breakpoints the side content falls down below the main content. Visibility: public |
sideContentPosition | sap.ui.layout.SideContentPosition | End | Determines whether the side content is on the left or on the right side of the main content. |
sideContentVisibility | sap.ui.layout.SideContentVisibility | ShowAboveS | Determines on which breakpoints the side content is visible. Visibility: public |
Default Aggregation: mainContent
Name | Cardinality | Type | Description |
---|---|---|---|
mainContent (default) | 0..n | sap.ui.core.Control |
Main content controls. |
sideContent | 0..n | sap.ui.core.Control |
Side content controls. |
Event | Description |
---|---|
breakpointChanged |
Fires when the current breakpoint has been changed. |
Method | Description |
---|---|
addMainContent |
Adds a control to the main content area. Only the main content part in the aggregation is re-rendered. |
addSideContent |
Adds a control to the side content area. Only the side content part in the aggregation is re-rendered. |
attachBreakpointChanged |
Attaches event handler When called, the context of the event handler (its Fires when the current breakpoint has been changed. |
destroyMainContent |
Destroys all the mainContent in the aggregation mainContent. |
destroySideContent |
Destroys all the sideContent in the aggregation sideContent. |
detachBreakpointChanged |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
sap.ui.layout.DynamicSideContent.extend |
Creates a new subclass of class sap.ui.layout.DynamicSideContent with name
|
fireBreakpointChanged |
Fires event breakpointChanged to attached listeners. |
getContainerQuery |
Gets current value of property containerQuery. If set to TRUE, then not the media Query (device screen size) but the size of the container, surrounding the control, defines the current range. Default value is |
getCurrentBreakpoint |
Returns the breakpoint for the current state of the control. If the control is not rendered yet, this method will return |
getEqualSplit |
Gets current value of property equalSplit. Defines whether the control is in equal split mode. In this mode, the side and the main content take 50:50 percent of the container on all screen sizes except for phone, where the main and side contents are switching visibility using the toggle method. Default value is |
getMainContent |
Gets content of aggregation mainContent. Main content controls. |
sap.ui.layout.DynamicSideContent.getMetadata |
Returns a metadata object for class sap.ui.layout.DynamicSideContent. |
getScrollDelegate |
Returns a scroll helper object used to handle scrolling. |
getShowMainContent |
Gets current value of property showMainContent. Determines whether the main content is visible or hidden. Default value is |
getShowSideContent |
Gets current value of property showSideContent. Determines whether the side content is visible or hidden. Note: If both Default value is |
getSideContent |
Gets content of aggregation sideContent. Side content controls. |
getSideContentFallDown |
Gets current value of property sideContentFallDown. Determines on which breakpoints the side content falls down below the main content. Default value is |
getSideContentPosition |
Gets current value of property sideContentPosition. Determines whether the side content is on the left or on the right side of the main content. Default value is |
getSideContentVisibility |
Gets current value of property sideContentVisibility. Determines on which breakpoints the side content is visible. Default value is |
indexOfMainContent |
Checks for the provided |
indexOfSideContent |
Checks for the provided |
insertMainContent |
Inserts a mainContent into the aggregation mainContent. |
insertSideContent |
Inserts a sideContent into the aggregation sideContent. |
isMainContentVisible |
Checks if the main content is visible. |
isSideContentVisible |
Checks if the side content is visible. |
removeAllMainContent |
Removes all the controls from the aggregation mainContent. Additionally, it unregisters them from the hosting UIArea. |
removeAllSideContent |
Removes all the controls from the aggregation sideContent. Additionally, it unregisters them from the hosting UIArea. |
removeMainContent |
Removes a mainContent from the aggregation mainContent. |
removeSideContent |
Removes a sideContent from the aggregation sideContent. |
setContainerQuery |
Sets a new value for property containerQuery. If set to TRUE, then not the media Query (device screen size) but the size of the container, surrounding the control, defines the current range. When called with a value of Default value is |
setEqualSplit |
Sets or unsets the page in equalSplit mode. |
setShowMainContent |
Sets the showMainContent property. |
setShowSideContent |
Sets the showSideContent property. |
setSideContentFallDown |
Sets a new value for property sideContentFallDown. Determines on which breakpoints the side content falls down below the main content. When called with a value of Default value is |
setSideContentPosition |
Sets a new value for property sideContentPosition. Determines whether the side content is on the left or on the right side of the main content. When called with a value of Default value is |
setSideContentVisibility |
Sets the sideContentVisibility property. |
toggle |
Used for the toggle button functionality. When the control is on a phone screen size only, one control area is visible. This helper method is used to implement a button/switch for changing between the main and side content areas. Only works if the current breakpoint is "S". |
Adds a control to the main content area. Only the main content part in the aggregation is re-rendered.
Param | Type | DefaultValue | Description |
---|---|---|---|
oControl | object |
Object to be added in the aggregation |
Adds a control to the side content area. Only the side content part in the aggregation is re-rendered.
Param | Type | DefaultValue | Description |
---|---|---|---|
oControl | object |
Object to be added in the aggregation |
Attaches event handler fnFunction
to the breakpointChanged event of this sap.ui.layout.DynamicSideContent
.
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.ui.layout.DynamicSideContent
itself.
Fires when the current breakpoint has been 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 |
Detaches event handler fnFunction
from the breakpointChanged event of this sap.ui.layout.DynamicSideContent
.
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.ui.layout.DynamicSideContent 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 breakpointChanged to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
currentBreakpoint | string |
Gets current value of property containerQuery.
If set to TRUE, then not the media Query (device screen size) but the size of the container, surrounding the control, defines the current range.
Default value is false
.
Returns the breakpoint for the current state of the control.
If the control is not rendered yet, this method will return undefined
, as current break point calculation is based on the parent container width.
Gets current value of property equalSplit.
Defines whether the control is in equal split mode. In this mode, the side and the main content take 50:50 percent of the container on all screen sizes except for phone, where the main and side contents are switching visibility using the toggle method.
Default value is false
.
Returns a metadata object for class sap.ui.layout.DynamicSideContent.
Returns a scroll helper object used to handle scrolling.
Param | Type | DefaultValue | Description |
---|---|---|---|
oControl | object |
The control instance that requested the scroll helper |
Gets current value of property showMainContent.
Determines whether the main content is visible or hidden.
Default value is true
.
Gets current value of property showSideContent.
Determines whether the side content is visible or hidden.
Note: If both showSideContent
and showMainContent
properties are set to true
, use the toggle
method for showing the side content on phone.
Default value is true
.
Gets current value of property sideContentFallDown.
Determines on which breakpoints the side content falls down below the main content.
Default value is OnMinimumWidth
.
Gets current value of property sideContentPosition.
Determines whether the side content is on the left or on the right side of the main content.
Default value is End
.
Gets current value of property sideContentVisibility.
Determines on which breakpoints the side content is visible.
Default value is ShowAboveS
.
Checks for the provided sap.ui.core.Control
in the aggregation mainContent. and returns its index if found or -1 otherwise.
Param | Type | DefaultValue | Description |
---|---|---|---|
oMainContent | sap.ui.core.Control |
The mainContent whose index is looked for |
Checks for the provided sap.ui.core.Control
in the aggregation sideContent. and returns its index if found or -1 otherwise.
Param | Type | DefaultValue | Description |
---|---|---|---|
oSideContent | sap.ui.core.Control |
The sideContent whose index is looked for |
Inserts a mainContent into the aggregation mainContent.
Param | Type | DefaultValue | Description |
---|---|---|---|
oMainContent | sap.ui.core.Control |
The mainContent to insert; if empty, nothing is inserted |
|
iIndex | int |
The |
Inserts a sideContent into the aggregation sideContent.
Param | Type | DefaultValue | Description |
---|---|---|---|
oSideContent | sap.ui.core.Control |
The sideContent to insert; if empty, nothing is inserted |
|
iIndex | int |
The |
Removes all the controls from the aggregation mainContent.
Additionally, it unregisters them from the hosting UIArea.
Removes all the controls from the aggregation sideContent.
Additionally, it unregisters them from the hosting UIArea.
Removes a mainContent from the aggregation mainContent.
Param | Type | DefaultValue | Description |
---|---|---|---|
vMainContent | int string sap.ui.core.Control |
The mainContent to remove or its index or id |
Removes a sideContent from the aggregation sideContent.
Param | Type | DefaultValue | Description |
---|---|---|---|
vSideContent | int string sap.ui.core.Control |
The sideContent to remove or its index or id |
Sets a new value for property containerQuery.
If set to TRUE, then not the media Query (device screen size) but the size of the container, surrounding the control, defines the current range.
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 or unsets the page in equalSplit mode.
Param | Type | DefaultValue | Description |
---|---|---|---|
bState | boolean |
Determines if the page is set to equalSplit mode |
Sets the showMainContent property.
Param | Type | DefaultValue | Description |
---|---|---|---|
bVisible | boolean |
Determines if the main content part is visible |
|
bSuppressVisualUpdate | boolean |
Determines if the visual state is updated |
Sets the showSideContent property.
Param | Type | DefaultValue | Description |
---|---|---|---|
bVisible | boolean |
Determines if the side content part is visible |
|
bSuppressVisualUpdate | boolean |
Determines if the visual state is updated |
Sets a new value for property sideContentFallDown.
Determines on which breakpoints the side content falls down below the main content.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is OnMinimumWidth
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sSideContentFallDown | sap.ui.layout.SideContentFallDown | OnMinimumWidth |
New value for property |
Sets a new value for property sideContentPosition.
Determines whether the side content is on the left or on the right side of the main content.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is End
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sSideContentPosition | sap.ui.layout.SideContentPosition | End |
New value for property |
Sets the sideContentVisibility property.
Param | Type | DefaultValue | Description |
---|---|---|---|
sVisibility | sap.ui.layout.SideContentVisibility |
Determines on which breakpoints the side content is visible. |
|
bSuppressVisualUpdate | boolean |
Determines if the visual state is updated |