class sap.ui.layout.DynamicSideContent

Visiblity: public
UX Guidelines: Dynamic Side Content
Implements:
Available since: N/A
Module: sap/ui/layout/DynamicSideContent
Application Component: CA-UI5-CTR

Layout control that allows additional (side) content to be displayed dynamically.

Overview

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.

Usage

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.

Responsive Behavior

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.

This control can be a drop target.

Constructor

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


Properties

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 showSideContent and showMainContent properties are set to true, use the toggle method for showing the side content on phone.

Visibility: public
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.

Since: 1.36.

Visibility: public
sideContentVisibility sap.ui.layout.SideContentVisibility ShowAboveS

Determines on which breakpoints the side content is visible.

Visibility: public

Aggregations

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.


Events Overview

Event Description
breakpointChanged

Fires when the current breakpoint has been changed.

Since: 1.32.

breakpointChanged

Fires when the current breakpoint has been changed.

Since: 1.32.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
currentBreakpoint string

Methods Overview

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 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.

destroyMainContent

Destroys all the mainContent in the aggregation mainContent.

destroySideContent

Destroys all the sideContent in the aggregation sideContent.

detachBreakpointChanged

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.

sap.ui.layout.DynamicSideContent.extend

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.

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 false.

getCurrentBreakpoint

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.

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 false.

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 true.

getShowSideContent

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.

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 OnMinimumWidth.

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 End.

getSideContentVisibility

Gets current value of property sideContentVisibility.

Determines on which breakpoints the side content is visible.

Default value is ShowAboveS.

indexOfMainContent

Checks for the provided sap.ui.core.Control in the aggregation mainContent. and returns its index if found or -1 otherwise.

indexOfSideContent

Checks for the provided sap.ui.core.Control in the aggregation sideContent. and returns its index if found or -1 otherwise.

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 null or undefined, the default value of the property will be restored.

Default value is false.

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 null or undefined, the default value of the property will be restored.

Default value is OnMinimumWidth.

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 null or undefined, the default value of the property will be restored.

Default value is End.

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".

addMainContent

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

addSideContent

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

attachBreakpointChanged

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 sap.ui.layout.DynamicSideContent itself

destroyMainContent

Destroys all the mainContent in the aggregation mainContent.

destroySideContent

Destroys all the sideContent in the aggregation sideContent.

detachBreakpointChanged

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

sap.ui.layout.DynamicSideContent.extend

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

fireBreakpointChanged

Fires event breakpointChanged to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

currentBreakpoint string

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 false.

getCurrentBreakpoint

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.

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 false.

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.

Param Type DefaultValue Description
oControl object

The control instance that requested the scroll helper

getShowMainContent

Gets current value of property showMainContent.

Determines whether the main content is visible or hidden.

Default value is true.

getShowSideContent

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.

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 OnMinimumWidth.

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 End.

getSideContentVisibility

Gets current value of property sideContentVisibility.

Determines on which breakpoints the side content is visible.

Default value is ShowAboveS.

indexOfMainContent

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

indexOfSideContent

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

insertMainContent

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 0-based index the mainContent should be inserted at; for a negative value of iIndex, the mainContent is inserted at position 0; for a value greater than the current size of the aggregation, the mainContent is inserted at the last position

insertSideContent

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 0-based index the sideContent should be inserted at; for a negative value of iIndex, the sideContent is inserted at position 0; for a value greater than the current size of the aggregation, the sideContent is inserted at the last position

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.

Param Type DefaultValue Description
vMainContent int string sap.ui.core.Control

The mainContent to remove or its index or id

removeSideContent

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

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 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 containerQuery

setEqualSplit

Sets or unsets the page in equalSplit mode.

Param Type DefaultValue Description
bState boolean

Determines if the page is set to equalSplit mode

setShowMainContent

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

setShowSideContent

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

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 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 sideContentFallDown

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 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 sideContentPosition

setSideContentVisibility

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

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".