class sap.f.DynamicPage

Control sample: sap.f.DynamicPage
Visiblity: public
UX Guidelines: Dynamic Page
Implements:
Available since: N/A
Module: sap/f/DynamicPage
Application Component: CA-UI5-CTR

A layout control, representing a web page, consisting of a title, header with dynamic behavior, a content area, and an optional floating footer.

Overview

The control consist of several components:

Usage

Use the DynamicPage if you need to have a title, that is always visible and a header, that has configurable Expanding/Snapping functionality. If you don't need the Expanding/Snapping functionality it is better to use the sap.m.Page as a lighter control.

Responsive Behavior

The responsive behavior of the DynamicPage depends on the behavior of the content that is displayed. To adjust the DynamicPage content padding, the sapUiContentPadding, sapUiNoContentPadding, and sapUiResponsiveContentPadding CSS classes can be used.

This control can be a drop target.

Constructor

Constructor for a new DynamicPage.

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.DynamicPage(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
backgroundDesign sap.m.PageBackgroundDesign Standard

Determines the background color of DynamicPage.

Since: 1.68.

Visibility: public
fitContent boolean false

Forces the content container of the DynamicPage to make room for stretchable controls in the content aggregation to fill exactly the visible space between the header and the footer.

Notes:

  • Enable this property only if the control of the content aggregation is configured to automatically stretch to fill the available height, which means that the content would appear squashed in height when this property is disabled. Such stretchable controls may be sap.ui.table.Table and sap.ui.table.AnalyticalTable depending on their settings.
  • It is not recommended to enable this property for controls that do not stretch in height (and appear properly when this property is disabled).

Visibility: public
headerExpanded boolean true

Determines whether the header is expanded.

The header can be also expanded/collapsed by user interaction, which requires the property to be internally mutated by the control to reflect the changed state.

Note: As of version 1.48, you can initialize the control in collapsed header state by setting this property to false.

Visibility: public
headerPinned boolean false

Determines whether the DynamicPageHeader is pinned.

The property can be changed programmatically or in the occurrence of the following user interactions:

  • Toggling the pin/unpin button of DynamicPageHeader
  • Snapping the DynamicPageHeader by explicitly clicking on the DynamicPageTitle

Note: The property will only apply if the header is effectively pinnable, i.e. if the following conditions are met:

  • DynamicPageHeader pinnable property is true
  • DynamicPageHeader is expanded
  • DynamicPage preserveHeaderStateOnScroll property is effectively disabled


Since: 1.93.

Visibility: public
preserveHeaderStateOnScroll boolean false

Preserves the current header state when scrolling. For example, if the user expands the header by clicking on the title and then scrolls down the page, the header will remain expanded.

Note: Based on internal rules, the value of the property is not always taken into account - for example, when the control`s title and header are with height larger than the given threshold.

Visibility: public
showFooter boolean false

Determines whether the footer is visible.

Visibility: public
toggleHeaderOnTitleClick boolean true

Determines whether the user can switch between the expanded/collapsed states of the DynamicPageHeader by clicking on the DynamicPageTitle or by using the expand/collapse visual indicators, positioned at the bottom of the DynamicPageTitle and the DynamicPageHeader. If set to false, the DynamicPageTitle is not clickable, the visual indicators are not available and the application must provide other means for expanding/collapsing the DynamicPageHeader, if necessary.

Note: This property is taken into account only if a non-empty header aggregation is provided.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
_scrollBar 0..1 sap.ui.core.Control

DynamicPage custom ScrollBar.

content 0..1 sap.ui.core.Control

DynamicPage content.

Note: You can change the default paddings by adding the following CSS classes:

  • sapUiContentPadding
  • sapUiNoContentPadding
  • sapUiResponsiveContentPadding
For more information, see Using Container Content Padding CSS Classes.

Note: The SAP Fiori Design guidelines require that the DynamicPageHeader's content and the DynamicPage's content are aligned vertically. When using sap.ui.layout.form.Form, sap.m.Panel, sap.m.Table and sap.m.List in the content area of DynamicPage, if the content is not already aligned, you need to adjust their left text offset to achieve the vertical alignment. To do this, apply the sapFDynamicPageAlignContent CSS class to them and set their width property to auto (if not set by default).

Example:

 <Panel class=“sapFDynamicPageAlignContent” width=“auto”></Panel> 

Please keep in mind that the alignment is not possible in the following cases:

  • When the controls are placed in an sap.ui.layout.Grid or other layout controls that use overflow:hidden CSS property
  • In case any of the following CSS classes is applied to DynamicPage: sapUiContentPadding, sapUiNoContentPadding or sapUiResponsiveContentPadding

footer 0..1 sap.m.IBar

DynamicPage floating footer.

header 0..1 sap.f.DynamicPageHeader

DynamicPage header.

landmarkInfo 0..1 sap.f.DynamicPageAccessibleLandmarkInfo

Accessible landmark settings to be applied on the containers of the sap.f.DynamicPage control.

If not set, no landmarks will be written.

Since: 1.61.

title 0..1 sap.f.DynamicPageTitle

DynamicPage title.


Associations

Name Cardinality Type Description
stickySubheaderProvider 0..1 sap.f.IDynamicPageStickyContent

Association of Controls / IDs, that provide sticky subheader content. All controls that provide this content have to implement the sap.f.IDynamicPageStickyContent interface.

Since: 1.65.


Events Overview

Event Description
pinnedStateChange

The event is fired when the headerPinned property is changed via user interaction.

Since: 1.93.

pinnedStateChange

The event is fired when the headerPinned property is changed via user interaction.

Since: 1.93.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
pinned boolean

False or True values indicate the new pinned property value.


Methods Overview

Method Description
attachPinnedStateChange

Attaches event handler fnFunction to the pinnedStateChange event of this sap.f.DynamicPage.

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

The event is fired when the headerPinned property is changed via user interaction.

destroyContent

Destroys the content in the aggregation content.

destroyFooter

Destroys the footer in the aggregation footer.

destroyHeader

Destroys the header in the aggregation header.

destroyLandmarkInfo

Destroys the landmarkInfo in the aggregation landmarkInfo.

destroyTitle

Destroys the title in the aggregation title.

detachPinnedStateChange

Detaches event handler fnFunction from the pinnedStateChange event of this sap.f.DynamicPage.

The passed function and listener object must match the ones used for event registration.

sap.f.DynamicPage.extend

Creates a new subclass of class sap.f.DynamicPage 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.

firePinnedStateChange

Fires event pinnedStateChange to attached listeners.

getBackgroundDesign

Gets current value of property backgroundDesign.

Determines the background color of DynamicPage.

Default value is Standard.

getContent

Gets content of aggregation content.

DynamicPage content.

Note: You can change the default paddings by adding the following CSS classes:

  • sapUiContentPadding
  • sapUiNoContentPadding
  • sapUiResponsiveContentPadding
For more information, see Using Container Content Padding CSS Classes.

Note: The SAP Fiori Design guidelines require that the DynamicPageHeader's content and the DynamicPage's content are aligned vertically. When using sap.ui.layout.form.Form, sap.m.Panel, sap.m.Table and sap.m.List in the content area of DynamicPage, if the content is not already aligned, you need to adjust their left text offset to achieve the vertical alignment. To do this, apply the sapFDynamicPageAlignContent CSS class to them and set their width property to auto (if not set by default).

Example:

 <Panel class=“sapFDynamicPageAlignContent” width=“auto”></Panel> 

Please keep in mind that the alignment is not possible in the following cases:

  • When the controls are placed in an sap.ui.layout.Grid or other layout controls that use overflow:hidden CSS property
  • In case any of the following CSS classes is applied to DynamicPage: sapUiContentPadding, sapUiNoContentPadding or sapUiResponsiveContentPadding

getFitContent

Gets current value of property fitContent.

Forces the content container of the DynamicPage to make room for stretchable controls in the content aggregation to fill exactly the visible space between the header and the footer.

Notes:

  • Enable this property only if the control of the content aggregation is configured to automatically stretch to fill the available height, which means that the content would appear squashed in height when this property is disabled. Such stretchable controls may be sap.ui.table.Table and sap.ui.table.AnalyticalTable depending on their settings.
  • It is not recommended to enable this property for controls that do not stretch in height (and appear properly when this property is disabled).

Default value is false.

getFooter

Gets content of aggregation footer.

DynamicPage floating footer.

getHeader

Gets content of aggregation header.

DynamicPage header.

getHeaderExpanded

Gets current value of property headerExpanded.

Determines whether the header is expanded.

The header can be also expanded/collapsed by user interaction, which requires the property to be internally mutated by the control to reflect the changed state.

Note: As of version 1.48, you can initialize the control in collapsed header state by setting this property to false.

Default value is true.

getHeaderPinned

Gets current value of property headerPinned.

Determines whether the DynamicPageHeader is pinned.

The property can be changed programmatically or in the occurrence of the following user interactions:

  • Toggling the pin/unpin button of DynamicPageHeader
  • Snapping the DynamicPageHeader by explicitly clicking on the DynamicPageTitle

Note: The property will only apply if the header is effectively pinnable, i.e. if the following conditions are met:

  • DynamicPageHeader pinnable property is true
  • DynamicPageHeader is expanded
  • DynamicPage preserveHeaderStateOnScroll property is effectively disabled

Default value is false.

getLandmarkInfo

Gets content of aggregation landmarkInfo.

Accessible landmark settings to be applied on the containers of the sap.f.DynamicPage control.

If not set, no landmarks will be written.

sap.f.DynamicPage.getMetadata

Returns a metadata object for class sap.f.DynamicPage.

getPreserveHeaderStateOnScroll

Gets current value of property preserveHeaderStateOnScroll.

Preserves the current header state when scrolling. For example, if the user expands the header by clicking on the title and then scrolls down the page, the header will remain expanded.

Note: Based on internal rules, the value of the property is not always taken into account - for example, when the control`s title and header are with height larger than the given threshold.

Default value is false.

getScrollDelegate

Returns the sap.ui.core.ScrollEnablement delegate which is used with this control.

getShowFooter

Gets current value of property showFooter.

Determines whether the footer is visible.

Default value is false.

getStickySubheaderProvider

ID of the element which is the current target of the association stickySubheaderProvider, or null.

getTitle

Gets content of aggregation title.

DynamicPage title.

getToggleHeaderOnTitleClick

Gets current value of property toggleHeaderOnTitleClick.

Determines whether the user can switch between the expanded/collapsed states of the DynamicPageHeader by clicking on the DynamicPageTitle or by using the expand/collapse visual indicators, positioned at the bottom of the DynamicPageTitle and the DynamicPageHeader. If set to false, the DynamicPageTitle is not clickable, the visual indicators are not available and the application must provide other means for expanding/collapsing the DynamicPageHeader, if necessary.

Note: This property is taken into account only if a non-empty header aggregation is provided.

Default value is true.

setBackgroundDesign

Sets a new value for property backgroundDesign.

Determines the background color of DynamicPage.

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

Default value is Standard.

setContent

Sets the aggregated content.

setFitContent

Sets a new value for property fitContent.

Forces the content container of the DynamicPage to make room for stretchable controls in the content aggregation to fill exactly the visible space between the header and the footer.

Notes:

  • Enable this property only if the control of the content aggregation is configured to automatically stretch to fill the available height, which means that the content would appear squashed in height when this property is disabled. Such stretchable controls may be sap.ui.table.Table and sap.ui.table.AnalyticalTable depending on their settings.
  • It is not recommended to enable this property for controls that do not stretch in height (and appear properly when this property is disabled).

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

Default value is false.

setFooter

Sets the aggregated footer.

setHeader

Sets the aggregated header.

setHeaderExpanded

Sets a new value for property headerExpanded.

Determines whether the header is expanded.

The header can be also expanded/collapsed by user interaction, which requires the property to be internally mutated by the control to reflect the changed state.

Note: As of version 1.48, you can initialize the control in collapsed header state by setting this property to false.

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

Default value is true.

setHeaderPinned

Sets a new value for property headerPinned.

Determines whether the DynamicPageHeader is pinned.

The property can be changed programmatically or in the occurrence of the following user interactions:

  • Toggling the pin/unpin button of DynamicPageHeader
  • Snapping the DynamicPageHeader by explicitly clicking on the DynamicPageTitle

Note: The property will only apply if the header is effectively pinnable, i.e. if the following conditions are met:

  • DynamicPageHeader pinnable property is true
  • DynamicPageHeader is expanded
  • DynamicPage preserveHeaderStateOnScroll property is effectively disabled

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

Default value is false.

setLandmarkInfo

Sets the aggregated landmarkInfo.

setPreserveHeaderStateOnScroll

Sets a new value for property preserveHeaderStateOnScroll.

Preserves the current header state when scrolling. For example, if the user expands the header by clicking on the title and then scrolls down the page, the header will remain expanded.

Note: Based on internal rules, the value of the property is not always taken into account - for example, when the control`s title and header are with height larger than the given threshold.

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

Default value is false.

setShowFooter

Sets a new value for property showFooter.

Determines whether the footer is visible.

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

Default value is false.

setStickySubheaderProvider

Sets the associated stickySubheaderProvider.

setTitle

Sets the aggregated title.

setToggleHeaderOnTitleClick

Sets a new value for property toggleHeaderOnTitleClick.

Determines whether the user can switch between the expanded/collapsed states of the DynamicPageHeader by clicking on the DynamicPageTitle or by using the expand/collapse visual indicators, positioned at the bottom of the DynamicPageTitle and the DynamicPageHeader. If set to false, the DynamicPageTitle is not clickable, the visual indicators are not available and the application must provide other means for expanding/collapsing the DynamicPageHeader, if necessary.

Note: This property is taken into account only if a non-empty header aggregation is provided.

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

Default value is true.

attachPinnedStateChange

Attaches event handler fnFunction to the pinnedStateChange event of this sap.f.DynamicPage.

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

The event is fired when the headerPinned property is changed via user interaction.

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.f.DynamicPage itself

destroyContent

Destroys the content in the aggregation content.

destroyFooter

Destroys the footer in the aggregation footer.

destroyHeader

Destroys the header in the aggregation header.

destroyLandmarkInfo

Destroys the landmarkInfo in the aggregation landmarkInfo.

destroyTitle

Destroys the title in the aggregation title.

detachPinnedStateChange

Detaches event handler fnFunction from the pinnedStateChange event of this sap.f.DynamicPage.

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.f.DynamicPage.extend

Creates a new subclass of class sap.f.DynamicPage 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

firePinnedStateChange

Fires event pinnedStateChange to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

pinned boolean

False or True values indicate the new pinned property value.

getBackgroundDesign

Gets current value of property backgroundDesign.

Determines the background color of DynamicPage.

Default value is Standard.

getContent

Gets content of aggregation content.

DynamicPage content.

Note: You can change the default paddings by adding the following CSS classes:

For more information, see Using Container Content Padding CSS Classes.

Note: The SAP Fiori Design guidelines require that the DynamicPageHeader's content and the DynamicPage's content are aligned vertically. When using sap.ui.layout.form.Form, sap.m.Panel, sap.m.Table and sap.m.List in the content area of DynamicPage, if the content is not already aligned, you need to adjust their left text offset to achieve the vertical alignment. To do this, apply the sapFDynamicPageAlignContent CSS class to them and set their width property to auto (if not set by default).

Example:

 <Panel class=“sapFDynamicPageAlignContent” width=“auto”></Panel> 

Please keep in mind that the alignment is not possible in the following cases:

getFitContent

Gets current value of property fitContent.

Forces the content container of the DynamicPage to make room for stretchable controls in the content aggregation to fill exactly the visible space between the header and the footer.

Notes:

Default value is false.

getFooter

Gets content of aggregation footer.

DynamicPage floating footer.

getHeader

Gets content of aggregation header.

DynamicPage header.

getHeaderExpanded

Gets current value of property headerExpanded.

Determines whether the header is expanded.

The header can be also expanded/collapsed by user interaction, which requires the property to be internally mutated by the control to reflect the changed state.

Note: As of version 1.48, you can initialize the control in collapsed header state by setting this property to false.

Default value is true.

getHeaderPinned

Gets current value of property headerPinned.

Determines whether the DynamicPageHeader is pinned.

The property can be changed programmatically or in the occurrence of the following user interactions:

Note: The property will only apply if the header is effectively pinnable, i.e. if the following conditions are met:

Default value is false.

getLandmarkInfo

Gets content of aggregation landmarkInfo.

Accessible landmark settings to be applied on the containers of the sap.f.DynamicPage control.

If not set, no landmarks will be written.

sap.f.DynamicPage.getMetadata

Returns a metadata object for class sap.f.DynamicPage.

getPreserveHeaderStateOnScroll

Gets current value of property preserveHeaderStateOnScroll.

Preserves the current header state when scrolling. For example, if the user expands the header by clicking on the title and then scrolls down the page, the header will remain expanded.

Note: Based on internal rules, the value of the property is not always taken into account - for example, when the control`s title and header are with height larger than the given threshold.

Default value is false.

getScrollDelegate

Returns the sap.ui.core.ScrollEnablement delegate which is used with this control.

getShowFooter

Gets current value of property showFooter.

Determines whether the footer is visible.

Default value is false.

getStickySubheaderProvider

ID of the element which is the current target of the association stickySubheaderProvider, or null.

getTitle

Gets content of aggregation title.

DynamicPage title.

getToggleHeaderOnTitleClick

Gets current value of property toggleHeaderOnTitleClick.

Determines whether the user can switch between the expanded/collapsed states of the DynamicPageHeader by clicking on the DynamicPageTitle or by using the expand/collapse visual indicators, positioned at the bottom of the DynamicPageTitle and the DynamicPageHeader. If set to false, the DynamicPageTitle is not clickable, the visual indicators are not available and the application must provide other means for expanding/collapsing the DynamicPageHeader, if necessary.

Note: This property is taken into account only if a non-empty header aggregation is provided.

Default value is true.

setBackgroundDesign

Sets a new value for property backgroundDesign.

Determines the background color of DynamicPage.

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

Default value is Standard.

Param Type DefaultValue Description
sBackgroundDesign sap.m.PageBackgroundDesign Standard

New value for property backgroundDesign

setContent

Sets the aggregated content.

Param Type DefaultValue Description
oContent sap.ui.core.Control

The content to set

setFitContent

Sets a new value for property fitContent.

Forces the content container of the DynamicPage to make room for stretchable controls in the content aggregation to fill exactly the visible space between the header and the footer.

Notes:

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
bFitContent boolean false

New value for property fitContent

setFooter

Sets the aggregated footer.

Param Type DefaultValue Description
oFooter sap.m.IBar

The footer to set

setHeader

Sets the aggregated header.

Param Type DefaultValue Description
oHeader sap.f.DynamicPageHeader

The header to set

setHeaderExpanded

Sets a new value for property headerExpanded.

Determines whether the header is expanded.

The header can be also expanded/collapsed by user interaction, which requires the property to be internally mutated by the control to reflect the changed state.

Note: As of version 1.48, you can initialize the control in collapsed header state by setting this property to false.

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

Default value is true.

Param Type DefaultValue Description
bHeaderExpanded boolean true

New value for property headerExpanded

setHeaderPinned

Sets a new value for property headerPinned.

Determines whether the DynamicPageHeader is pinned.

The property can be changed programmatically or in the occurrence of the following user interactions:

Note: The property will only apply if the header is effectively pinnable, i.e. if the following conditions are met:

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
bHeaderPinned boolean false

New value for property headerPinned

setLandmarkInfo

Sets the aggregated landmarkInfo.

Param Type DefaultValue Description
oLandmarkInfo sap.f.DynamicPageAccessibleLandmarkInfo

The landmarkInfo to set

setPreserveHeaderStateOnScroll

Sets a new value for property preserveHeaderStateOnScroll.

Preserves the current header state when scrolling. For example, if the user expands the header by clicking on the title and then scrolls down the page, the header will remain expanded.

Note: Based on internal rules, the value of the property is not always taken into account - for example, when the control`s title and header are with height larger than the given threshold.

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
bPreserveHeaderStateOnScroll boolean false

New value for property preserveHeaderStateOnScroll

setShowFooter

Sets a new value for property showFooter.

Determines whether the footer is visible.

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
bShowFooter boolean false

New value for property showFooter

setStickySubheaderProvider

Sets the associated stickySubheaderProvider.

Param Type DefaultValue Description
oStickySubheaderProvider sap.ui.core.ID sap.f.IDynamicPageStickyContent

ID of an element which becomes the new target of this stickySubheaderProvider association; alternatively, an element instance may be given

setTitle

Sets the aggregated title.

Param Type DefaultValue Description
oTitle sap.f.DynamicPageTitle

The title to set

setToggleHeaderOnTitleClick

Sets a new value for property toggleHeaderOnTitleClick.

Determines whether the user can switch between the expanded/collapsed states of the DynamicPageHeader by clicking on the DynamicPageTitle or by using the expand/collapse visual indicators, positioned at the bottom of the DynamicPageTitle and the DynamicPageHeader. If set to false, the DynamicPageTitle is not clickable, the visual indicators are not available and the application must provide other means for expanding/collapsing the DynamicPageHeader, if necessary.

Note: This property is taken into account only if a non-empty header aggregation is provided.

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

Default value is true.

Param Type DefaultValue Description
bToggleHeaderOnTitleClick boolean true

New value for property toggleHeaderOnTitleClick