Class sap.ui.layout.DynamicSideContentModule: sap/ui/layout/DynamicSideContent

extends Control

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

  • Main vs. side content ratio is 75 vs. 25 percent (with a minimum of 320px each).
  • If the application defines a trigger, the side content can be hidden.

Screen width <= 1440 px and > 720px

  • Main vs. side content ratio is 66.666 vs. 33.333 percent (with a minimum of 320px each). If the side content width falls below 320 px, it automatically slides under the main content, unless the app development team specifies that it should disappear.

Screen width <= 720 px (for example on a mobile device)

  • In this case, the side content automatically disappears from the screen (unless specified to stay under the content) and can be triggered from a pre-set trigger (specified within the app). When the side content is triggered, it replaces the main content. We recommend that you always place the trigger for the side content in the same location, such as in the app footer.

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.


Since: 1.30.
Constructor Summary
new sap.ui.layout.DynamicSideContent(sId?, mSettings?)Constructor for a new DynamicSideContent.
Event Summary
breakpointChanged(oControlEvent)Fires when the current breakpoint has been changed.
Events borrowed from class sap.ui.core.Control
Method Summary
sap.ui.layout.DynamicSideContent.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.ui.layout.DynamicSideContent with name sClassName and enriches it with the information contained in oClassInfo.
sap.ui.layout.DynamicSideContent.getMetadata()Returns a metadata object for class sap.ui.layout.DynamicSideContent.
addMainContent(oControl)Adds a control to the main content area.
addSideContent(oControl)Adds a control to the side content area.
attachBreakpointChanged(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the breakpointChanged event of this sap.ui.layout.DynamicSideContent.
destroyMainContent()Destroys all the mainContent in the aggregation mainContent.
destroySideContent()Destroys all the sideContent in the aggregation sideContent.
detachBreakpointChanged(fnFunction, oListener)Detaches event handler fnFunction from the breakpointChanged event of this sap.ui.layout.DynamicSideContent.
fireBreakpointChanged(mParameters?)Fires event breakpointChanged to attached listeners.
getContainerQuery()Gets current value of property containerQuery.
getCurrentBreakpoint()Returns the breakpoint for the current state of the control.
getEqualSplit()Gets current value of property equalSplit.
getMainContent()Gets content of aggregation mainContent.
getShowMainContent()Gets the value of showMainContent property.
getShowSideContent()Gets the value of showSideContent property.
getSideContent()Gets content of aggregation sideContent.
getSideContentFallDown()Gets current value of property sideContentFallDown.
getSideContentPosition()Gets current value of property sideContentPosition.
getSideContentVisibility()Gets current value of property sideContentVisibility.
indexOfMainContent(oMainContent)Checks for the provided sap.ui.core.Control in the aggregation mainContent.
indexOfSideContent(oSideContent)Checks for the provided sap.ui.core.Control in the aggregation sideContent.
insertMainContent(oMainContent, iIndex)Inserts a mainContent into the aggregation mainContent.
insertSideContent(oSideContent, iIndex)Inserts a sideContent into the aggregation sideContent.
removeAllMainContent()Removes all the controls from the aggregation mainContent.
removeAllSideContent()Removes all the controls from the aggregation sideContent.
removeMainContent(vMainContent)Removes a mainContent from the aggregation mainContent.
removeSideContent(vSideContent)Removes a sideContent from the aggregation sideContent.
setContainerQuery(bContainerQuery)Sets a new value for property containerQuery.
setEqualSplit(bState?)Sets or unsets the page in equalSplit mode.
setShowMainContent(bVisible, bSuppressVisualUpdate)Sets the showMainContent property.
setShowSideContent(bVisible, bSuppressVisualUpdate)Sets the showSideContent property.
setSideContentFallDown(sSideContentFallDown)Sets a new value for property sideContentFallDown.
setSideContentPosition(sSideContentPosition)Sets a new value for property sideContentPosition.
setSideContentVisibility(sSideContentVisibility)Sets a new value for property sideContentVisibility.
toggle()Used for the toggle button functionality.
Constructor Detail
new sap.ui.layout.DynamicSideContent(sId?, mSettings?)

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 for a general description of the syntax of the settings object.

The supported settings are:

In addition, all settings applicable to the base type sap.ui.core.Control can be used as well.

Parameters:
stringsId?ID for the new control, generated automatically if no ID is given
objectmSettings?Initial settings for the new control
Event Detail
breakpointChanged(oControlEvent)
Fires when the current breakpoint has been changed.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
stringoControlEvent.getParameters.currentBreakpoint
Since:
1.32
Method Detail
sap.ui.layout.DynamicSideContent.extend(sClassName, oClassInfo?, FNMetaImpl?): function

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.

Parameters:
stringsClassNameName of the class being created
objectoClassInfo?Object literal with information about the class
functionFNMetaImpl?Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
functionCreated class / constructor function
sap.ui.layout.DynamicSideContent.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.ui.layout.DynamicSideContent.
Returns:
sap.ui.base.MetadataMetadata object describing this class
addMainContent(oControl): sap.ui.layout.DynamicSideContent
Adds a control to the main content area. Only the main content part in the aggregation is re-rendered.
Parameters:
objectoControlObject to be added in the aggregation
Returns:
sap.ui.layout.DynamicSideContentthis pointer for chaining
addSideContent(oControl): sap.ui.layout.DynamicSideContent
Adds a control to the side content area. Only the side content part in the aggregation is re-rendered.
Parameters:
objectoControlObject to be added in the aggregation
Returns:
sap.ui.layout.DynamicSideContentthis pointer for chaining
attachBreakpointChanged(oData?, fnFunction, oListener?): sap.ui.layout.DynamicSideContent

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.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.ui.layout.DynamicSideContent itself
Returns:
sap.ui.layout.DynamicSideContentReference to this in order to allow method chaining
Since:
1.32
destroyMainContent(): sap.ui.layout.DynamicSideContent
Destroys all the mainContent in the aggregation mainContent.
Returns:
sap.ui.layout.DynamicSideContentReference to this in order to allow method chaining
destroySideContent(): sap.ui.layout.DynamicSideContent
Destroys all the sideContent in the aggregation sideContent.
Returns:
sap.ui.layout.DynamicSideContentReference to this in order to allow method chaining
detachBreakpointChanged(fnFunction, oListener): sap.ui.layout.DynamicSideContent

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.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.ui.layout.DynamicSideContentReference to this in order to allow method chaining
Since:
1.32
fireBreakpointChanged(mParameters?): sap.ui.layout.DynamicSideContent
Fires event breakpointChanged to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
stringmParameters.currentBreakpoint?
Returns:
sap.ui.layout.DynamicSideContentReference to this in order to allow method chaining
Since:
1.32
getContainerQuery(): boolean

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:
booleanValue of property containerQuery
getCurrentBreakpoint(): String
Returns the breakpoint for the current state of the control.
Returns:
StringcurrentBreakpoint
getEqualSplit(): boolean

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:
booleanValue of property equalSplit
getMainContent(): sap.ui.core.Control[]

Gets content of aggregation mainContent.

Main content controls.

Returns:
sap.ui.core.Control[]
getShowMainContent(): boolean
Gets the value of showMainContent property.
Returns:
booleanSide content visibility state
getShowSideContent(): boolean
Gets the value of showSideContent property.
Returns:
booleanSide content visibility state
getSideContent(): sap.ui.core.Control[]

Gets content of aggregation sideContent.

Side content controls.

Returns:
sap.ui.core.Control[]
getSideContentFallDown(): sap.ui.layout.SideContentFallDown

Gets current value of property sideContentFallDown.

Determines on which breakpoints the side content falls down below the main content.

Default value is OnMinimumWidth.

Returns:
sap.ui.layout.SideContentFallDownValue of property sideContentFallDown
getSideContentPosition(): sap.ui.layout.SideContentPosition

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.

Returns:
sap.ui.layout.SideContentPositionValue of property sideContentPosition
Since:
1.36
getSideContentVisibility(): sap.ui.layout.SideContentVisibility

Gets current value of property sideContentVisibility.

Determines on which breakpoints the side content is visible.

Default value is ShowAboveS.

Returns:
sap.ui.layout.SideContentVisibilityValue of property sideContentVisibility
indexOfMainContent(oMainContent): int
Checks for the provided sap.ui.core.Control in the aggregation mainContent. and returns its index if found or -1 otherwise.
Parameters:
sap.ui.core.ControloMainContentThe mainContent whose index is looked for
Returns:
intThe index of the provided control in the aggregation if found, or -1 otherwise
indexOfSideContent(oSideContent): int
Checks for the provided sap.ui.core.Control in the aggregation sideContent. and returns its index if found or -1 otherwise.
Parameters:
sap.ui.core.ControloSideContentThe sideContent whose index is looked for
Returns:
intThe index of the provided control in the aggregation if found, or -1 otherwise
insertMainContent(oMainContent, iIndex): sap.ui.layout.DynamicSideContent
Inserts a mainContent into the aggregation mainContent.
Parameters:
sap.ui.core.ControloMainContentthe mainContent to insert; if empty, nothing is inserted
intiIndexthe 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
Returns:
sap.ui.layout.DynamicSideContentReference to this in order to allow method chaining
insertSideContent(oSideContent, iIndex): sap.ui.layout.DynamicSideContent
Inserts a sideContent into the aggregation sideContent.
Parameters:
sap.ui.core.ControloSideContentthe sideContent to insert; if empty, nothing is inserted
intiIndexthe 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
Returns:
sap.ui.layout.DynamicSideContentReference to this in order to allow method chaining
removeAllMainContent(): sap.ui.core.Control[]

Removes all the controls from the aggregation mainContent.

Additionally, it unregisters them from the hosting UIArea.

Returns:
sap.ui.core.Control[]An array of the removed elements (might be empty)
removeAllSideContent(): sap.ui.core.Control[]

Removes all the controls from the aggregation sideContent.

Additionally, it unregisters them from the hosting UIArea.

Returns:
sap.ui.core.Control[]An array of the removed elements (might be empty)
removeMainContent(vMainContent): sap.ui.core.Control
Removes a mainContent from the aggregation mainContent.
Parameters:
int|string|sap.ui.core.ControlvMainContentThe mainContent to remove or its index or id
Returns:
sap.ui.core.ControlThe removed mainContent or null
removeSideContent(vSideContent): sap.ui.core.Control
Removes a sideContent from the aggregation sideContent.
Parameters:
int|string|sap.ui.core.ControlvSideContentThe sideContent to remove or its index or id
Returns:
sap.ui.core.ControlThe removed sideContent or null
setContainerQuery(bContainerQuery): sap.ui.layout.DynamicSideContent

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.

Parameters:
booleanbContainerQueryNew value for property containerQuery
Returns:
sap.ui.layout.DynamicSideContentReference to this in order to allow method chaining
setEqualSplit(bState?): sap.ui.layout.DynamicSideContent
Sets or unsets the page in equalSplit mode.
Parameters:
booleanbState?Determines if the page is set to equalSplit mode
Returns:
sap.ui.layout.DynamicSideContentthis pointer for chaining
setShowMainContent(bVisible, bSuppressVisualUpdate): sap.ui.layout.DynamicSideContent
Sets the showMainContent property.
Parameters:
booleanbVisibleDetermines if the main content part is visible
booleanbSuppressVisualUpdateDetermines if the visual state is updated
Returns:
sap.ui.layout.DynamicSideContentthis pointer for chaining
setShowSideContent(bVisible, bSuppressVisualUpdate): sap.ui.layout.DynamicSideContent
Sets the showSideContent property.
Parameters:
booleanbVisibleDetermines if the side content part is visible
booleanbSuppressVisualUpdateDetermines if the visual state is updated
Returns:
sap.ui.layout.DynamicSideContentthis pointer for chaining
setSideContentFallDown(sSideContentFallDown): sap.ui.layout.DynamicSideContent

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.

Parameters:
sap.ui.layout.SideContentFallDownsSideContentFallDownNew value for property sideContentFallDown
Returns:
sap.ui.layout.DynamicSideContentReference to this in order to allow method chaining
setSideContentPosition(sSideContentPosition): sap.ui.layout.DynamicSideContent

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.

Parameters:
sap.ui.layout.SideContentPositionsSideContentPositionNew value for property sideContentPosition
Returns:
sap.ui.layout.DynamicSideContentReference to this in order to allow method chaining
Since:
1.36
setSideContentVisibility(sSideContentVisibility): sap.ui.layout.DynamicSideContent

Sets a new value for property sideContentVisibility.

Determines on which breakpoints the side content is visible.

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

Default value is ShowAboveS.

Parameters:
sap.ui.layout.SideContentVisibilitysSideContentVisibilityNew value for property sideContentVisibility
Returns:
sap.ui.layout.DynamicSideContentReference to this in order to allow method chaining
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".
Returns:
sap.ui.layout.DynamicSideContentthis pointer for chaining