class sap.ui.comp.smartvariants.SmartVariantManagement

Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/comp/smartvariants/SmartVariantManagement
Application Component: CA-UI5-CMP

Overview

The SmartVariantManagement control is a specialization of the VariantManagement control and communicates with the flexibility library that offers SAPUI5 flexibility to manage the variants.

Usage

You can use this control in combination with the following controls:



Documentation links:


Constructor

Constructor for a new SmartVariantManagement.
The call sequence is as follows:
A control for which personalization is used has to be registered first via the personalizableControls association. Then it has to call the initialise method with the arguments fCallback function which will be called once the personalization data has been retrieved and oPersoControl, the control itself.
Note: the function callback has to be defined in the personalizable control.
The old behavior, where the control has to register to the initialise event, before the initialise method call, should not be used any longer and is not supported at all for the page variant scenarios.

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.comp.smartvariants.SmartVariantManagement(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.ui.generic.template components only.

Since: 1.85.

Visibility: public
entitySet string

The OData entity set whose metadata is used to create the variant items based on the SelectionPresentationVariant annotation.

Visibility: public
persistencyKey string

Key used to access personalization data.

Visibility: public

Borrowed Properties

Name Type Default Value Description
defaultVariantKey string

Provides a string value to set the default variant. Used for the save dialog. Has no effect on the selected variant.

Since: 1.22.0.

Visibility: public
enabled boolean true

Can be set to true or false depending on whether you want to enable or disable the control.

Since: 1.22.0.

Visibility: public
inErrorState boolean false

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

Since: 1.52.0.

Visibility: public
initialSelectionKey string

Enables the setting of the initially selected variant.

Since: 1.22.0.

Visibility: public
lifecycleSupport boolean false

Enables the lifecycle support. If set to true, the VariantManagement control handles the transport information for shared variants.

Since: 1.26.0.

Visibility: public
selectionKey string

The key of the currently selected item. Returns null if the default item list is selected. This property is calculated when accessing it via the getSelectionKey method. The corresponding setSelectionKey method is not supported. The access via the standard set/getProperty is also not supported.

Since: 1.24.0.

Visibility: public
showCreateTile boolean false

Indicates that a Create Tile is visible in the Create dialog.

Since: 1.26.0.

Visibility: public
showExecuteOnSelection boolean false

Indicates that Execute on Selection is visible in the Save Variant and the Manage Variants dialogs.

Since: 1.26.0.

Visibility: public
showSetAsDefault boolean true

Indicates that set as default is visible in the Save Variant and the Manage Variants dialogs.

Since: 1.44.0.

Visibility: public
showShare boolean false

Indicates that the Public checkbox is visible in the Save View and the Manage Views dialogs. Selecting this checkbox allows you to share variants with other users.

Since: 1.26.0.

Visibility: public
standardItemAuthor string SAP

Defines the author of the standard variant, for example, the name of the own company.

Since: 1.86.

Visibility: public
standardItemText string

Overwrites the default Standard variant title.

Since: 1.28.0.

Visibility: public
useFavorites boolean false

Indicates that the 'Favorites' feature is used. Only variants marked as favorites will be displayed in the variant list.

Since: 1.50.0.

Visibility: public
variantCreationByUserAllowed boolean true

Indicates that end users are allowed to create variants.

Since: 1.85.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
personalizableControls 0..n sap.ui.comp.smartvariants.PersonalizableInfo

All controls that rely on variant handling have to be added to this aggregation.

Borrowed Aggregations

Name Cardinality Type Description
items 0..n sap.ui.core.Item

Items displayed by the VariantManagement control.
Deprecated as of version 1.26.0. Replaced by association variantItems

variantItems 0..n sap.ui.comp.variants.VariantItem

Variant items displayed by the VariantManagement control.

Since: 1.26.0.


Events Overview

Event Description
afterSave

This event is fired after all changes are successfully stored.

initialise

This event is fired when the SmartVariantManagement control is initialized.

save

This event is fired after a variant has been saved.

afterSave

This event is fired after all changes are successfully stored.

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

initialise

This event is fired when the SmartVariantManagement control is initialized.

Replaced by providing the personalizable control and the callback via the <code>initialise</code>-method.
Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

save

This event is fired after a variant has been saved.

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

If the property showCreateTile is set, the Create Tile checkbox is shown and its value is passed to this event parameter.
If the property showCreateTile is not set, this event parameter is skipped.


Methods Overview

Method Description
addPersonalizableControl

Registers all controls interested and relying on variant handling.

attachAfterSave

Attaches event handler fnFunction to the afterSave event of this sap.ui.comp.smartvariants.SmartVariantManagement.

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.comp.smartvariants.SmartVariantManagement itself.

This event is fired after all changes are successfully stored.

attachInitialise

Attaches event handler fnFunction to the initialise event of this sap.ui.comp.smartvariants.SmartVariantManagement.

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.comp.smartvariants.SmartVariantManagement itself.

This event is fired when the SmartVariantManagement control is initialized.

Since 1.38.0 Replaced by providing the personalizable control and the callback via the <code>initialise</code>-method.
attachSave

Attaches event handler fnFunction to the save event of this sap.ui.comp.smartvariants.SmartVariantManagement.

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.comp.smartvariants.SmartVariantManagement itself.

This event is fired after a variant has been saved.

currentVariantSetModified

Sets the dirty flag of the current variant.

destroyPersonalizableControls

Destroys all the personalizableControls in the aggregation personalizableControls.

detachAfterSave

Detaches event handler fnFunction from the afterSave event of this sap.ui.comp.smartvariants.SmartVariantManagement.

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

detachInitialise

Detaches event handler fnFunction from the initialise event of this sap.ui.comp.smartvariants.SmartVariantManagement.

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

Since 1.38.0 Replaced by providing the personalizable control and the callback via the <code>initialise</code>-method.
detachSave

Detaches event handler fnFunction from the save event of this sap.ui.comp.smartvariants.SmartVariantManagement.

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

sap.ui.comp.smartvariants.SmartVariantManagement.extend

Creates a new subclass of class sap.ui.comp.smartvariants.SmartVariantManagement 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.comp.smartvariants.SmartVariantManagementBase.extend.

fireAfterSave

Fires event afterSave to attached listeners.

fireInitialise

Fires event initialise to attached listeners.

Since 1.38.0 Replaced by providing the personalizable control and the callback via the <code>initialise</code>-method.
getCurrentVariantId

Retrieves the current variant ID. For a standard variant, an empty string is returned.

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.ui.generic.template components only.

Default value is empty string.

getEntitySet

Gets current value of property entitySet.

The OData entity set whose metadata is used to create the variant items based on the SelectionPresentationVariant annotation.

getExecuteOnStandard

Returns the current 'apply automatically' behavior for the standard variant. If called before the variants are completely initialized undefined is returned.

sap.ui.comp.smartvariants.SmartVariantManagement.getMetadata

Returns a metadata object for class sap.ui.comp.smartvariants.SmartVariantManagement.

getPersistencyKey

Gets current value of property persistencyKey.

Key used to access personalization data.

getPersonalizableControls

Gets content of aggregation personalizableControls.

All controls that rely on variant handling have to be added to this aggregation.

getStandardVariant

Returns the standard variant.

getVariantContent

Retrieves the variant content.

indexOfPersonalizableControl

Checks for the provided sap.ui.comp.smartvariants.PersonalizableInfo in the aggregation personalizableControls. and returns its index if found or -1 otherwise.

initialise

Initializes the control by retrieving the variants from SAPUI5 flexibility. Once the initialization has been completed, the controls for personalization are notified via the initialise event.

insertPersonalizableControl

Inserts a personalizableControl into the aggregation personalizableControls.

isPageVariant

Determines if the SmartVariantManagement instance is a page variant.

registerApplyAutomaticallyOnStandardVariant

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

removeAllPersonalizableControls

Removes all registered personalizable controls.

removePersonalizableControl

Removes a registered personalizable control.

removePersonalizableControlById

Removes a registered personalizable control.

setCurrentVariantId

Sets the current variant ID.

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.ui.generic.template 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.

setEntitySet

The entity set name from OData metadata, with which the smart variant control must be bound.

setExecuteOnStandard

Allows the FE-based applications to set the 'apply automatically' behavior for the standard variant. If 'apply automatically' end-user changes for the standard variant exists, they will be reapplied, after the setting. So, basically existing end-user changes always overwrite the intention.

setPersistencyKey

Sets a new value for property persistencyKey.

Key used to access personalization data.

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

addPersonalizableControl

Registers all controls interested and relying on variant handling.

Param Type DefaultValue Description
oCurrentControlInfo sap.ui.comp.smartvariants.PersonalizableInfo

Wrapper for the personalizable control

attachAfterSave

Attaches event handler fnFunction to the afterSave event of this sap.ui.comp.smartvariants.SmartVariantManagement.

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.comp.smartvariants.SmartVariantManagement itself.

This event is fired after all changes are successfully stored.

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.comp.smartvariants.SmartVariantManagement itself

attachInitialise

Attaches event handler fnFunction to the initialise event of this sap.ui.comp.smartvariants.SmartVariantManagement.

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.comp.smartvariants.SmartVariantManagement itself.

This event is fired when the SmartVariantManagement control is initialized.

Since 1.38.0 Replaced by providing the personalizable control and the callback via the <code>initialise</code>-method.
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.comp.smartvariants.SmartVariantManagement itself

attachSave

Attaches event handler fnFunction to the save event of this sap.ui.comp.smartvariants.SmartVariantManagement.

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.comp.smartvariants.SmartVariantManagement itself.

This event is fired after a variant has been saved.

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.comp.smartvariants.SmartVariantManagement itself

currentVariantSetModified

Sets the dirty flag of the current variant.

Param Type DefaultValue Description
bFlag boolean

The value indicating the dirty state of the current variant

destroyPersonalizableControls

Destroys all the personalizableControls in the aggregation personalizableControls.

detachAfterSave

Detaches event handler fnFunction from the afterSave event of this sap.ui.comp.smartvariants.SmartVariantManagement.

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

detachInitialise

Detaches event handler fnFunction from the initialise event of this sap.ui.comp.smartvariants.SmartVariantManagement.

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

Since 1.38.0 Replaced by providing the personalizable control and the callback via the <code>initialise</code>-method.
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.comp.smartvariants.SmartVariantManagement.

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.comp.smartvariants.SmartVariantManagement.extend

Creates a new subclass of class sap.ui.comp.smartvariants.SmartVariantManagement 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.comp.smartvariants.SmartVariantManagementBase.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

fireAfterSave

Fires event afterSave to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireInitialise

Fires event initialise to attached listeners.

Since 1.38.0 Replaced by providing the personalizable control and the callback via the <code>initialise</code>-method.
Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

getCurrentVariantId

Retrieves the current variant ID. For a standard variant, an empty string is returned.

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.ui.generic.template components only.

Default value is empty string.

getEntitySet

Gets current value of property entitySet.

The OData entity set whose metadata is used to create the variant items based on the SelectionPresentationVariant annotation.

getExecuteOnStandard

Returns the current 'apply automatically' behavior for the standard variant. If called before the variants are completely initialized undefined is returned.

sap.ui.comp.smartvariants.SmartVariantManagement.getMetadata

Returns a metadata object for class sap.ui.comp.smartvariants.SmartVariantManagement.

getPersistencyKey

Gets current value of property persistencyKey.

Key used to access personalization data.

getPersonalizableControls

Gets content of aggregation personalizableControls.

All controls that rely on variant handling have to be added to this aggregation.

getStandardVariant

Returns the standard variant.

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

Current personalizable control

getVariantContent

Retrieves the variant content.

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

Current personalizable control

sKey string

The variant key

indexOfPersonalizableControl

Checks for the provided sap.ui.comp.smartvariants.PersonalizableInfo in the aggregation personalizableControls. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oPersonalizableControl sap.ui.comp.smartvariants.PersonalizableInfo

The personalizableControl whose index is looked for

initialise

Initializes the control by retrieving the variants from SAPUI5 flexibility. Once the initialization has been completed, the controls for personalization are notified via the initialise event.

Param Type DefaultValue Description
fCallback function

Function will be called whenever the data for the personalizable control is received

oPersoControl sap.ui.core.Control

Current control that can be personalized

insertPersonalizableControl

Inserts a personalizableControl into the aggregation personalizableControls.

Param Type DefaultValue Description
oPersonalizableControl sap.ui.comp.smartvariants.PersonalizableInfo

The personalizableControl to insert; if empty, nothing is inserted

iIndex int

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

isPageVariant

Determines if the SmartVariantManagement instance is a page variant.

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.

removeAllPersonalizableControls

Removes all registered personalizable controls.

removePersonalizableControl

Removes a registered personalizable control.

Param Type DefaultValue Description
oCurrentControlInfo sap.ui.comp.smartvariants.PersonalizableInfo

wrapper for the personalizable control

removePersonalizableControlById

Removes a registered personalizable control.

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

the personalizable control

setCurrentVariantId

Sets the current variant ID.

Param Type DefaultValue Description
sVariantId string

ID of the variant

bDoNotApplyVariant boolean

If set to true, the applyVariant method is not executed yet.

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.ui.generic.template 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

setEntitySet

The entity set name from OData metadata, with which the smart variant control must be bound.

Param Type DefaultValue Description
sEntitySetName string

The entity set

setExecuteOnStandard

Allows the FE-based applications to set the 'apply automatically' behavior for the standard variant. If 'apply automatically' end-user changes for the standard variant exists, they will be reapplied, after the setting. So, basically existing end-user changes always overwrite the intention.

Param Type DefaultValue Description
bSelect boolean

defines the 'apply automatically' intention for the standard variant

setPersistencyKey

Sets a new value for property persistencyKey.

Key used to access personalization data.

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

Param Type DefaultValue Description
sPersistencyKey string

New value for property persistencyKey