class sap.m.P13nDialog

Control sample: sap.m.P13nDialog
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Extends: sap.m.Dialog
Module: sap/m/P13nDialog
Application Component: CA-UI5-CMP

The P13nDialog control provides a dialog that contains one or more panels. On each of the panels, one or more changes with regards to a table can be processed. For example, a panel to set a column to invisible, change the order of the columns or a panel to sort or filter tables.


Constructor

Constructor for a new P13nDialog.

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.m.P13nDialog(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
initialVisiblePanelType string

This property determines which panel is initially shown when dialog is opened. If not defined then the first visible panel of panels aggregation is taken. Setting value after the dialog is opened has no effect anymore. Due to extensibility reason the type should be string. So it is feasible to add a custom panel without expanding the type.

Visibility: public
showReset boolean false

This property determines whether the 'Restore' button is shown inside the dialog. If this property is set to true, clicking the 'Reset' button will trigger the reset event sending a notification that model data must be reset.

Visibility: public
showResetEnabled boolean false

This property determines whether the 'Restore' button is enabled and is taken into account only if showReset is set to true.

Since: 1.36.0.

Visibility: public
validationExecutor object

Calls the validation listener once all panel-relevant validation checks have been done. This callback function is called in order to perform cross-model validation checks.

Visibility: public

Borrowed Properties

Name Type Default Value Description
closeOnNavigation boolean true

Indicates whether the Dialog will be closed automatically when a routing navigation occurs.

Since: 1.72.

Visibility: public
contentHeight sap.ui.core.CSSSize

Preferred height of the content in the Dialog. If the preferred height is bigger than the available space on a screen, it will be overwritten by the maximum available height on a screen in order to make sure that the Dialog isn't cut off.

Since: 1.12.1.

Visibility: public
contentWidth sap.ui.core.CSSSize

Preferred width of the content in the Dialog. This property affects the width of the Dialog on a phone in landscape mode, a tablet or a desktop, because the Dialog has a fixed width on a phone in portrait mode. If the preferred width is less than the minimum width of the Dialog or more than the available width of the screen, it will be overwritten by the min or max value. The current mininum value of the Dialog width on tablet is 400px.

Since: 1.12.1.

Visibility: public
draggable boolean false

Indicates whether the Dialog is draggable. If this property is set to true, the Dialog will be draggable by its header. This property has a default value false. The Dialog can be draggable only in desktop mode.

Since: 1.30.

Visibility: public
escapeHandler function

This property expects a function with one parameter of type Promise. In the function, you should call either resolve() or reject() on the Promise object.
The function allows you to define custom behavior which will be executed when the Escape key is pressed. By default, when the Escape key is pressed, the Dialog is immediately closed.

Since: 1.44.

Visibility: public
horizontalScrolling boolean true

Indicates if the user can scroll horizontally inside the Dialog when the content is bigger than the content area. The Dialog detects if there's sap.m.NavContainer, sap.m.Page, sap.m.ScrollContainer or sap.m.SplitContainer as a direct child added to the Dialog. If there is, the Dialog will turn off scrolling by setting this property to false, automatically ignoring the existing value of the property.

Since: 1.15.1.

Visibility: public
icon sap.ui.core.URI

Icon displayed in the Dialog header. This icon is invisible on the iOS platform and it is density-aware. You can use the density convention (@2, @1.5, etc.) to provide higher resolution image for higher density screen.

Visibility: public
resizable boolean false

Indicates whether the Dialog is resizable. If this property is set to true, the Dialog will have a resize handler in its bottom right corner. This property has a default value false. The Dialog can be resizable only in desktop mode.

Since: 1.30.

Visibility: public
showHeader boolean true

Determines whether the header is shown inside the Dialog. If this property is set to true, the text and icon properties are ignored. This property has a default value true.

Since: 1.15.1.

Visibility: public
state sap.ui.core.ValueState None

Affects the icon and the title color.

If a value other than None is set, a predefined icon will be added to the Dialog. Setting the icon property will overwrite the predefined icon.

Since: 1.11.2.

Visibility: public
stretch boolean false

Determines if the Dialog will be stretched to full screen on mobile. On desktop, the Dialog will be stretched to approximately 90% of the viewport. This property is only applicable to a Standard Dialog. Message-type Dialog ignores it.

Since: 1.13.1.

Visibility: public
stretchOnPhone boolean false

Determines whether the Dialog will be displayed on full screen on a phone.

Since: 1.11.2.

Visibility: public
title string

Title text appears in the Dialog header.

Visibility: public
titleAlignment sap.m.TitleAlignment Auto

Specifies the Title alignment (theme specific). If set to TitleAlignment.Auto, the Title will be aligned as it is set in the theme (if not set, the default value is center); Other possible values are TitleAlignment.Start (left or right depending on LTR/RTL), and TitleAlignment.Center (centered)

Since: 1.72.

Visibility: public
type sap.m.DialogType Standard

The type of the Dialog. In some themes, the type Message will limit the Dialog width within 480px on tablet and desktop.

Visibility: public
verticalScrolling boolean true

Indicates if the user can scroll vertically inside the Dialog when the content is bigger than the content area. The Dialog detects if there's sap.m.NavContainer, sap.m.Page, sap.m.ScrollContainer or sap.m.SplitContainer as a direct child added to the Dialog. If there is, the Dialog will turn off scrolling by setting this property to false, automatically ignoring the existing value of this property.

Since: 1.15.1.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
panels 0..n sap.m.P13nPanel

The dialog panels displayed in the dialog.

Borrowed Aggregations

Name Cardinality Type Description
beginButton 0..1 sap.m.Button

The button which is rendered to the left side (right side in RTL mode) of the endButton in the footer area inside the Dialog. As of version 1.21.1, there's a new aggregation buttons created with which more than 2 buttons can be added to the footer area of the Dialog. If the new buttons aggregation is set, any change made to this aggregation has no effect anymore. With the Belize themes when running on a phone, this button (and the endButton together when set) is (are) rendered at the center of the footer area. While with the Quartz themes when running on a phone, this button (and the endButton together when set) is (are) rendered on the right side of the footer area. When running on other platforms, this button (and the endButton together when set) is (are) rendered at the right side (left side in RTL mode) of the footer area.

Since: 1.15.1.

buttons 0..n sap.m.Button

Buttons can be added to the footer area of the Dialog through this aggregation. When this aggregation is set, any change to the beginButton and endButton has no effect anymore. Buttons which are inside this aggregation are aligned at the right side (left side in RTL mode) of the footer instead of in the middle of the footer.

Since: 1.21.1.

content 0..n sap.ui.core.Control

The content inside the Dialog.
Note: When the content of the Dialog is comprised of controls that use position: absolute, such as SplitContainer, the Dialog has to have either stretch: true or contentHeight set.

customHeader 0..1 sap.m.IBar

When it is set, the icon, title and showHeader properties are ignored. Only the customHeader is shown as the header of the Dialog.

Since: 1.15.1.

endButton 0..1 sap.m.Button

The button which is rendered to the right side (left side in RTL mode) of the beginButton in the footer area inside the Dialog. As of version 1.21.1, there's a new aggregation buttons created with which more than 2 buttons can be added to the footer area of Dialog. If the new buttons aggregation is set, any change made to this aggregation has no effect anymore. With the Belize themes when running on a phone, this button (and the beginButton together when set) is (are) rendered at the center of the footer area. While with the Quartz themes when running on a phone, this button (and the beginButton together when set) is (are) rendered on the right side of the footer area. When running on other platforms, this button (and the beginButton together when set) is (are) rendered at the right side (left side in RTL mode) of the footer area.

Since: 1.15.1.

subHeader 0..1 sap.m.IBar

When a subHeader is assigned to the Dialog, it's rendered directly after the main header in the Dialog. The subHeader is out of the content area and won't be scrolled when the content size is bigger than the content area size.

Since: 1.12.2.


Events Overview

Event Description
cancel

Event fired if the 'cancel' button in P13nDialog is clicked.

ok

Event fired if the 'ok' button in P13nDialog is clicked.

reset

Event fired if the 'reset' button in P13nDialog is clicked.

cancel

Event fired if the 'cancel' button in P13nDialog is clicked.

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

ok

Event fired if the 'ok' button in P13nDialog is clicked.

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

reset

Event fired if the 'reset' button in P13nDialog is clicked.

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

Methods Overview

Method Description
addPanel

Adds some panel to the aggregation panels.

attachCancel

Attaches event handler fnFunction to the cancel event of this sap.m.P13nDialog.

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.m.P13nDialog itself.

Event fired if the 'cancel' button in P13nDialog is clicked.

attachOk

Attaches event handler fnFunction to the ok event of this sap.m.P13nDialog.

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.m.P13nDialog itself.

Event fired if the 'ok' button in P13nDialog is clicked.

attachReset

Attaches event handler fnFunction to the reset event of this sap.m.P13nDialog.

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.m.P13nDialog itself.

Event fired if the 'reset' button in P13nDialog is clicked.

bindPanels

Binds aggregation panels to model data.

See ManagedObject.bindAggregation for a detailed description of the possible properties of oBindingInfo.

destroyPanels

Destroys all the panels in the aggregation panels.

detachCancel

Detaches event handler fnFunction from the cancel event of this sap.m.P13nDialog.

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

detachOk

Detaches event handler fnFunction from the ok event of this sap.m.P13nDialog.

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

detachReset

Detaches event handler fnFunction from the reset event of this sap.m.P13nDialog.

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

sap.m.P13nDialog.extend

Creates a new subclass of class sap.m.P13nDialog 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.Dialog.extend.

fireCancel

Fires event cancel to attached listeners.

fireOk

Fires event ok to attached listeners.

fireReset

Fires event reset to attached listeners.

getInitialVisiblePanelType

Gets current value of property initialVisiblePanelType.

This property determines which panel is initially shown when dialog is opened. If not defined then the first visible panel of panels aggregation is taken. Setting value after the dialog is opened has no effect anymore. Due to extensibility reason the type should be string. So it is feasible to add a custom panel without expanding the type.

sap.m.P13nDialog.getMetadata

Returns a metadata object for class sap.m.P13nDialog.

getPanels

Gets content of aggregation panels.

The dialog panels displayed in the dialog.

getShowReset

Gets current value of property showReset.

This property determines whether the 'Restore' button is shown inside the dialog. If this property is set to true, clicking the 'Reset' button will trigger the reset event sending a notification that model data must be reset.

Default value is false.

getShowResetEnabled

Gets current value of property showResetEnabled.

This property determines whether the 'Restore' button is enabled and is taken into account only if showReset is set to true.

Default value is false.

getValidationExecutor

Gets current value of property validationExecutor.

Calls the validation listener once all panel-relevant validation checks have been done. This callback function is called in order to perform cross-model validation checks.

getVisiblePanel

Returns visible panel.

indexOfPanel

Checks for the provided sap.m.P13nPanel in the aggregation panels. and returns its index if found or -1 otherwise.

insertPanel

Inserts a panel into the aggregation panels.

removeAllPanels

Removes all the controls from the aggregation panels.

Additionally, it unregisters them from the hosting UIArea.

removePanel

Removes a panel from the aggregation panels.

setInitialVisiblePanelType

Sets a new value for property initialVisiblePanelType.

This property determines which panel is initially shown when dialog is opened. If not defined then the first visible panel of panels aggregation is taken. Setting value after the dialog is opened has no effect anymore. Due to extensibility reason the type should be string. So it is feasible to add a custom panel without expanding the type.

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

setShowReset

Sets a new value for property showReset.

This property determines whether the 'Restore' button is shown inside the dialog. If this property is set to true, clicking the 'Reset' button will trigger the reset event sending a notification that model data must be reset.

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

Default value is false.

setShowResetEnabled

Sets a new value for property showResetEnabled.

This property determines whether the 'Restore' button is enabled and is taken into account only if showReset is set to true.

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

Default value is false.

setValidationExecutor

Sets a new value for property validationExecutor.

Calls the validation listener once all panel-relevant validation checks have been done. This callback function is called in order to perform cross-model validation checks.

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

unbindPanels

Unbinds aggregation panels from model data.

addPanel

Adds some panel to the aggregation panels.

Param Type DefaultValue Description
oPanel sap.m.P13nPanel

The panel to add; if empty, nothing is inserted

attachCancel

Attaches event handler fnFunction to the cancel event of this sap.m.P13nDialog.

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.m.P13nDialog itself.

Event fired if the 'cancel' button in P13nDialog is clicked.

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.m.P13nDialog itself

attachOk

Attaches event handler fnFunction to the ok event of this sap.m.P13nDialog.

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.m.P13nDialog itself.

Event fired if the 'ok' button in P13nDialog is clicked.

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.m.P13nDialog itself

attachReset

Attaches event handler fnFunction to the reset event of this sap.m.P13nDialog.

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.m.P13nDialog itself.

Event fired if the 'reset' button in P13nDialog is clicked.

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.m.P13nDialog itself

bindPanels

Binds aggregation panels to model data.

See ManagedObject.bindAggregation for a detailed description of the possible properties of oBindingInfo.

Param Type DefaultValue Description
oBindingInfo sap.ui.base.ManagedObject.AggregationBindingInfo

The binding information

destroyPanels

Destroys all the panels in the aggregation panels.

detachCancel

Detaches event handler fnFunction from the cancel event of this sap.m.P13nDialog.

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

detachOk

Detaches event handler fnFunction from the ok event of this sap.m.P13nDialog.

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

detachReset

Detaches event handler fnFunction from the reset event of this sap.m.P13nDialog.

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.m.P13nDialog.extend

Creates a new subclass of class sap.m.P13nDialog 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.Dialog.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

fireCancel

Fires event cancel to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireOk

Fires event ok to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireReset

Fires event reset to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

getInitialVisiblePanelType

Gets current value of property initialVisiblePanelType.

This property determines which panel is initially shown when dialog is opened. If not defined then the first visible panel of panels aggregation is taken. Setting value after the dialog is opened has no effect anymore. Due to extensibility reason the type should be string. So it is feasible to add a custom panel without expanding the type.

sap.m.P13nDialog.getMetadata

Returns a metadata object for class sap.m.P13nDialog.

getPanels

Gets content of aggregation panels.

The dialog panels displayed in the dialog.

getShowReset

Gets current value of property showReset.

This property determines whether the 'Restore' button is shown inside the dialog. If this property is set to true, clicking the 'Reset' button will trigger the reset event sending a notification that model data must be reset.

Default value is false.

getShowResetEnabled

Gets current value of property showResetEnabled.

This property determines whether the 'Restore' button is enabled and is taken into account only if showReset is set to true.

Default value is false.

getValidationExecutor

Gets current value of property validationExecutor.

Calls the validation listener once all panel-relevant validation checks have been done. This callback function is called in order to perform cross-model validation checks.

getVisiblePanel

Returns visible panel.

indexOfPanel

Checks for the provided sap.m.P13nPanel in the aggregation panels. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oPanel sap.m.P13nPanel

The panel whose index is looked for

insertPanel

Inserts a panel into the aggregation panels.

Param Type DefaultValue Description
oPanel sap.m.P13nPanel

The panel to insert; if empty, nothing is inserted

iIndex int

The 0-based index the panel should be inserted at; for a negative value of iIndex, the panel is inserted at position 0; for a value greater than the current size of the aggregation, the panel is inserted at the last position

removeAllPanels

Removes all the controls from the aggregation panels.

Additionally, it unregisters them from the hosting UIArea.

removePanel

Removes a panel from the aggregation panels.

Param Type DefaultValue Description
vPanel int string sap.m.P13nPanel

The panel to remove or its index or id

setInitialVisiblePanelType

Sets a new value for property initialVisiblePanelType.

This property determines which panel is initially shown when dialog is opened. If not defined then the first visible panel of panels aggregation is taken. Setting value after the dialog is opened has no effect anymore. Due to extensibility reason the type should be string. So it is feasible to add a custom panel without expanding the type.

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

Param Type DefaultValue Description
sInitialVisiblePanelType string

New value for property initialVisiblePanelType

setShowReset

Sets a new value for property showReset.

This property determines whether the 'Restore' button is shown inside the dialog. If this property is set to true, clicking the 'Reset' button will trigger the reset event sending a notification that model data must be reset.

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

New value for property showReset

setShowResetEnabled

Sets a new value for property showResetEnabled.

This property determines whether the 'Restore' button is enabled and is taken into account only if showReset is set to true.

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

New value for property showResetEnabled

setValidationExecutor

Sets a new value for property validationExecutor.

Calls the validation listener once all panel-relevant validation checks have been done. This callback function is called in order to perform cross-model validation checks.

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

Param Type DefaultValue Description
oValidationExecutor object

New value for property validationExecutor

unbindPanels

Unbinds aggregation panels from model data.