class sap.ui.fl.variants.VariantManagement

Visiblity: public
UX Guidelines:
Implements: sap.m.IOverflowToolbarContent
Available since: N/A
Module: sap/ui/fl/variants/VariantManagement
Application Component: CA-UI5-FL

Can be used to manage variants. You can use this control in most controls that are enabled for key user adaptation.
Note: On the user interface, variants are generally referred to as "views".


Constructor

Constructor for a new VariantManagement.

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.fl.variants.VariantManagement(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
displayTextForExecuteOnSelectionForStandardVariant string empty string

Defines the Apply Automatically text for the standard variant in the Manage Views dialog if the application controls this behavior.


Note: the usage of this property is restricted to sap.fe components only.

Since: 1.85.

Visibility: public
editable boolean true

Indicates that the control is in edit state. If set to false, the footer of the Views list will be hidden.

Visibility: public
executeOnSelectionForStandardDefault boolean false

Determines the behavior for Apply Automatically if the standard variant is marked as the default variant.

Since: 1.80.

Visibility: public
inErrorState boolean false

Indicates that the control is in error state. If set to true, an error message will be displayed whenever the variant is opened.

Visibility: public
manualVariantKey boolean false

If set to true, the key for a vendor variant will be added manually.
Note:This flag is only used internally in the app variant scenarios.

Visibility: public
modelName string

Determines the name of the model. The binding context will be defined by the current ID.

Note: In a UI adaptation scenario, this property is not used at all, because the model name is $FlexVariants.

Visibility: public
resetOnContextChange boolean true

When set to false, doesn't reset the VariantManagement control to the default variant, when its binding context is changed.

Visibility: public
showSetAsDefault boolean true

Indicates that Set as Default is visible in the Save View and the Manage Views dialogs.

Visibility: public
updateVariantInURL boolean false

Determines the intention of setting the current variant based on passed information.

Note: The VariantManagement control does not react in any way to this property.

Visibility: public

Associations

Name Cardinality Type Description
for 0..n sap.ui.core.Control

Contains the controls for which the variant management is responsible.


Events Overview

Event Description
cancel

This event is fired when users presses the cancel button inside Save As dialog.

initialized

This event is fired when the model and context are set.

manage

This event is fired when users apply changes to variants in the Manage Views dialog.

save

This event is fired when the Save View dialog or the Save As dialog is closed with the save button.

select

This event is fired when a new variant is selected.

cancel

This event is fired when users presses the cancel button inside Save As dialog.

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

initialized

This event is fired when the model and context are set.

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

manage

This event is fired when users apply changes to variants in the Manage Views dialog.

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

save

This event is fired when the Save View dialog or the Save As dialog is closed with the save button.

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

Variant title

overwrite boolean

Indicates if an existing variant is overwritten or if a new variant is created.

key string

Variant key

execute boolean

Apply Automatically indicator

def boolean

The default variant indicator

select

This event is fired when a new variant is selected.

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

Variant key


Methods Overview

Method Description
addFor

Adds some for into the association for.

attachCancel

Attaches event handler fnFunction to the cancel event of this sap.ui.fl.variants.VariantManagement.

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.fl.variants.VariantManagement itself.

This event is fired when users presses the cancel button inside Save As dialog.

attachInitialized

Attaches event handler fnFunction to the initialized event of this sap.ui.fl.variants.VariantManagement.

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.fl.variants.VariantManagement itself.

This event is fired when the model and context are set.

attachManage

Attaches event handler fnFunction to the manage event of this sap.ui.fl.variants.VariantManagement.

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.fl.variants.VariantManagement itself.

This event is fired when users apply changes to variants in the Manage Views dialog.

attachSave

Attaches event handler fnFunction to the save event of this sap.ui.fl.variants.VariantManagement.

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.fl.variants.VariantManagement itself.

This event is fired when the Save View dialog or the Save As dialog is closed with the save button.

attachSelect

Attaches event handler fnFunction to the select event of this sap.ui.fl.variants.VariantManagement.

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.fl.variants.VariantManagement itself.

This event is fired when a new variant is selected.

detachCancel

Detaches event handler fnFunction from the cancel event of this sap.ui.fl.variants.VariantManagement.

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

detachInitialized

Detaches event handler fnFunction from the initialized event of this sap.ui.fl.variants.VariantManagement.

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

detachManage

Detaches event handler fnFunction from the manage event of this sap.ui.fl.variants.VariantManagement.

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

detachSave

Detaches event handler fnFunction from the save event of this sap.ui.fl.variants.VariantManagement.

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

detachSelect

Detaches event handler fnFunction from the select event of this sap.ui.fl.variants.VariantManagement.

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

sap.ui.fl.variants.VariantManagement.extend

Creates a new subclass of class sap.ui.fl.variants.VariantManagement 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.

fireCancel

Fires event cancel to attached listeners.

fireInitialized

Fires event initialized to attached listeners.

fireManage

Fires event manage to attached listeners.

fireSave

Fires event save to attached listeners.

fireSelect

Fires event select to attached listeners.

getApplyAutomaticallyOnVariant

Retrieves the apply automatically state for a variant.

getCurrentVariantKey

Gets the currently selected variant key.

getDisplayTextForExecuteOnSelectionForStandardVariant

Gets current value of property displayTextForExecuteOnSelectionForStandardVariant.

Defines the Apply Automatically text for the standard variant in the Manage Views dialog if the application controls this behavior.


Note: the usage of this property is restricted to sap.fe components only.

Default value is empty string.

getEditable

Gets current value of property editable.

Indicates that the control is in edit state. If set to false, the footer of the Views list will be hidden.

Default value is true.

getExecuteOnSelectionForStandardDefault

Gets current value of property executeOnSelectionForStandardDefault.

Determines the behavior for Apply Automatically if the standard variant is marked as the default variant.

Default value is false.

getFor

Returns array of IDs of the elements which are the current targets of the association for.

getInErrorState

Gets current value of property inErrorState.

Indicates that the control is in error state. If set to true, an error message will be displayed whenever the variant is opened.

Default value is false.

getManualVariantKey

Gets current value of property manualVariantKey.

If set to true, the key for a vendor variant will be added manually.
Note:This flag is only used internally in the app variant scenarios.

Default value is false.

sap.ui.fl.variants.VariantManagement.getMetadata

Returns a metadata object for class sap.ui.fl.variants.VariantManagement.

getModelName

Gets current value of property modelName.

Determines the name of the model. The binding context will be defined by the current ID.

Note: In a UI adaptation scenario, this property is not used at all, because the model name is $FlexVariants.

getModified

Determines if the current variant is modified.

getOverflowToolbarConfig

Required by the sap.m.IOverflowToolbarContent interface. Registers invalidations event which is fired when width of the control is changed.

getResetOnContextChange

Gets current value of property resetOnContextChange.

When set to false, doesn't reset the VariantManagement control to the default variant, when its binding context is changed.

Default value is true.

getShowSetAsDefault

Gets current value of property showSetAsDefault.

Indicates that Set as Default is visible in the Save View and the Manage Views dialogs.

Default value is true.

getTitle

Returns the title control of the VariantManagement. This is used in the key user scenario.

getUpdateVariantInURL

Gets current value of property updateVariantInURL.

Determines the intention of setting the current variant based on passed information.

Note: The VariantManagement control does not react in any way to this property.

Default value is false.

getVariants

Retrieves all variants.

registerApplyAutomaticallyOnStandardVariant

Registration of a callback function. The provided callback function is executed to check if apply automatically on standard variant should be considered.

removeAllFor

Removes all the controls in the association named for.

removeFor

Removes an for from the association named for.

setCurrentVariantKey

Sets the new selected variant.

setDisplayTextForExecuteOnSelectionForStandardVariant

Sets a new value for property displayTextForExecuteOnSelectionForStandardVariant.

Defines the Apply Automatically text for the standard variant in the Manage Views dialog if the application controls this behavior.


Note: the usage of this property is restricted to sap.fe components only.

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

Default value is empty string.

setEditable

Sets a new value for property editable.

Indicates that the control is in edit state. If set to false, the footer of the Views list will be hidden.

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

Default value is true.

setExecuteOnSelectionForStandardDefault

Sets a new value for property executeOnSelectionForStandardDefault.

Determines the behavior for Apply Automatically if the standard variant is marked as the default variant.

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

Default value is false.

setInErrorState

Sets a new value for property inErrorState.

Indicates that the control is in error state. If set to true, an error message will be displayed whenever the variant is opened.

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

Default value is false.

setManualVariantKey

Sets a new value for property manualVariantKey.

If set to true, the key for a vendor variant will be added manually.
Note:This flag is only used internally in the app variant scenarios.

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

Default value is false.

setModelName

Sets a new value for property modelName.

Determines the name of the model. The binding context will be defined by the current ID.

Note: In a UI adaptation scenario, this property is not used at all, because the model name is $FlexVariants.

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

setResetOnContextChange

Sets a new value for property resetOnContextChange.

When set to false, doesn't reset the VariantManagement control to the default variant, when its binding context is changed.

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

Default value is true.

setShowSetAsDefault

Sets a new value for property showSetAsDefault.

Indicates that Set as Default is visible in the Save View and the Manage Views dialogs.

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

Default value is true.

setUpdateVariantInURL

Sets a new value for property updateVariantInURL.

Determines the intention of setting the current variant based on passed information.

Note: The VariantManagement control does not react in any way to this property.

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

Default value is false.

addFor

Adds some for into the association for.

Param Type DefaultValue Description
vFor sap.ui.core.ID sap.ui.core.Control

The for to add; if empty, nothing is inserted

attachCancel

Attaches event handler fnFunction to the cancel event of this sap.ui.fl.variants.VariantManagement.

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.fl.variants.VariantManagement itself.

This event is fired when users presses the cancel button inside Save As dialog.

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.fl.variants.VariantManagement itself

attachInitialized

Attaches event handler fnFunction to the initialized event of this sap.ui.fl.variants.VariantManagement.

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.fl.variants.VariantManagement itself.

This event is fired when the model and context are set.

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.fl.variants.VariantManagement itself

attachManage

Attaches event handler fnFunction to the manage event of this sap.ui.fl.variants.VariantManagement.

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.fl.variants.VariantManagement itself.

This event is fired when users apply changes to variants in the Manage Views dialog.

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.fl.variants.VariantManagement itself

attachSave

Attaches event handler fnFunction to the save event of this sap.ui.fl.variants.VariantManagement.

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.fl.variants.VariantManagement itself.

This event is fired when the Save View dialog or the Save As dialog is closed with the save button.

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.fl.variants.VariantManagement itself

attachSelect

Attaches event handler fnFunction to the select event of this sap.ui.fl.variants.VariantManagement.

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.fl.variants.VariantManagement itself.

This event is fired when a new variant is selected.

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.fl.variants.VariantManagement itself

detachCancel

Detaches event handler fnFunction from the cancel event of this sap.ui.fl.variants.VariantManagement.

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

detachInitialized

Detaches event handler fnFunction from the initialized event of this sap.ui.fl.variants.VariantManagement.

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

detachManage

Detaches event handler fnFunction from the manage event of this sap.ui.fl.variants.VariantManagement.

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

detachSave

Detaches event handler fnFunction from the save event of this sap.ui.fl.variants.VariantManagement.

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

detachSelect

Detaches event handler fnFunction from the select event of this sap.ui.fl.variants.VariantManagement.

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.fl.variants.VariantManagement.extend

Creates a new subclass of class sap.ui.fl.variants.VariantManagement 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

fireCancel

Fires event cancel to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireInitialized

Fires event initialized to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireManage

Fires event manage to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireSave

Fires event save to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

name string

Variant title

overwrite boolean

Indicates if an existing variant is overwritten or if a new variant is created.

key string

Variant key

execute boolean

Apply Automatically indicator

def boolean

The default variant indicator

fireSelect

Fires event select to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

key string

Variant key

getApplyAutomaticallyOnVariant

Retrieves the apply automatically state for a variant.

Param Type DefaultValue Description
oVariant object

the inner variant object

getCurrentVariantKey

Gets the currently selected variant key.

getDisplayTextForExecuteOnSelectionForStandardVariant

Gets current value of property displayTextForExecuteOnSelectionForStandardVariant.

Defines the Apply Automatically text for the standard variant in the Manage Views dialog if the application controls this behavior.


Note: the usage of this property is restricted to sap.fe components only.

Default value is empty string.

getEditable

Gets current value of property editable.

Indicates that the control is in edit state. If set to false, the footer of the Views list will be hidden.

Default value is true.

getExecuteOnSelectionForStandardDefault

Gets current value of property executeOnSelectionForStandardDefault.

Determines the behavior for Apply Automatically if the standard variant is marked as the default variant.

Default value is false.

getFor

Returns array of IDs of the elements which are the current targets of the association for.

getInErrorState

Gets current value of property inErrorState.

Indicates that the control is in error state. If set to true, an error message will be displayed whenever the variant is opened.

Default value is false.

getManualVariantKey

Gets current value of property manualVariantKey.

If set to true, the key for a vendor variant will be added manually.
Note:This flag is only used internally in the app variant scenarios.

Default value is false.

sap.ui.fl.variants.VariantManagement.getMetadata

Returns a metadata object for class sap.ui.fl.variants.VariantManagement.

getModelName

Gets current value of property modelName.

Determines the name of the model. The binding context will be defined by the current ID.

Note: In a UI adaptation scenario, this property is not used at all, because the model name is $FlexVariants.

getModified

Determines if the current variant is modified.

getOverflowToolbarConfig

Required by the sap.m.IOverflowToolbarContent interface. Registers invalidations event which is fired when width of the control is changed.

getResetOnContextChange

Gets current value of property resetOnContextChange.

When set to false, doesn't reset the VariantManagement control to the default variant, when its binding context is changed.

Default value is true.

getShowSetAsDefault

Gets current value of property showSetAsDefault.

Indicates that Set as Default is visible in the Save View and the Manage Views dialogs.

Default value is true.

getTitle

Returns the title control of the VariantManagement. This is used in the key user scenario.

getUpdateVariantInURL

Gets current value of property updateVariantInURL.

Determines the intention of setting the current variant based on passed information.

Note: The VariantManagement control does not react in any way to this property.

Default value is false.

getVariants

Retrieves all variants.

registerApplyAutomaticallyOnStandardVariant

Registration of a callback function. The provided callback function is executed to check if apply automatically on standard variant should be considered.

Param Type DefaultValue Description
fCallBack function

Called when standard variant must be applied. It determines if apply automatically on standard variant should be considered.

removeAllFor

Removes all the controls in the association named for.

removeFor

Removes an for from the association named for.

Param Type DefaultValue Description
vFor int sap.ui.core.ID sap.ui.core.Control

The for to be removed or its index or ID

setCurrentVariantKey

Sets the new selected variant.

Param Type DefaultValue Description
sKey string

Key of the variant that should be selected.

setDisplayTextForExecuteOnSelectionForStandardVariant

Sets a new value for property displayTextForExecuteOnSelectionForStandardVariant.

Defines the Apply Automatically text for the standard variant in the Manage Views dialog if the application controls this behavior.


Note: the usage of this property is restricted to sap.fe components only.

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

Default value is empty string.

Param Type DefaultValue Description
sDisplayTextForExecuteOnSelectionForStandardVariant string ""

New value for property displayTextForExecuteOnSelectionForStandardVariant

setEditable

Sets a new value for property editable.

Indicates that the control is in edit state. If set to false, the footer of the Views list will be hidden.

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
bEditable boolean true

New value for property editable

setExecuteOnSelectionForStandardDefault

Sets a new value for property executeOnSelectionForStandardDefault.

Determines the behavior for Apply Automatically if the standard variant is marked as the default variant.

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

New value for property executeOnSelectionForStandardDefault

setInErrorState

Sets a new value for property inErrorState.

Indicates that the control is in error state. If set to true, an error message will be displayed whenever the variant is opened.

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

New value for property inErrorState

setManualVariantKey

Sets a new value for property manualVariantKey.

If set to true, the key for a vendor variant will be added manually.
Note:This flag is only used internally in the app variant scenarios.

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

New value for property manualVariantKey

setModelName

Sets a new value for property modelName.

Determines the name of the model. The binding context will be defined by the current ID.

Note: In a UI adaptation scenario, this property is not used at all, because the model name is $FlexVariants.

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

Param Type DefaultValue Description
sModelName string

New value for property modelName

setResetOnContextChange

Sets a new value for property resetOnContextChange.

When set to false, doesn't reset the VariantManagement control to the default variant, when its binding context is changed.

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
bResetOnContextChange boolean true

New value for property resetOnContextChange

setShowSetAsDefault

Sets a new value for property showSetAsDefault.

Indicates that Set as Default is visible in the Save View and the Manage Views dialogs.

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
bShowSetAsDefault boolean true

New value for property showSetAsDefault

setUpdateVariantInURL

Sets a new value for property updateVariantInURL.

Determines the intention of setting the current variant based on passed information.

Note: The VariantManagement control does not react in any way to this property.

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

New value for property updateVariantInURL