Updated: March 9, 2018

Variant Management

sap.ui.comp.variants.VariantManagement

Intro

Variants store view settings, such as filter settings or control parameters.

The filter settings consist of filter parameters, selection fields, and the layout of filters. They are set within the filter bar.

Control parameters are the sort order, filter and group settings, column visibility, and the layout of a table or chart. They are set within the toolbar of the control.

The variant management control enables the user to load, save, change, and maintain variants.

The smart variant management control saves both filter and control parameters in one page variant. It creates a page variant that includes all settings of the page content. The control is merged with the page title. Note that page variants cannot be combined with variants for other controls.

Information
Note on terminology:

On the user interface, we now call variants “views”, which is better understood by end users. To describe the SAPUI5 controls, however, we still speak of “variants” and “variant management”.

Usage

Use the variant management control if:

  • The user needs to save and load different filter settings to find the relevant data.
  • The user needs to save and load different layouts (for example, a table) to display data in different views.
  • The user needs to save the settings for the whole page, including the filter settings and table layout. In this case, use the smart variant management control.

Responsiveness

Size S (Smartphone)

On phones, the My Views dialog for selecting variants, the Manage Views dialog, and the Save View dialog open in full screen mode.

Variant selection
Variant selection
Manage variants
Manage variants
Save variant
Save variant

Size M (Tablet)

Variant selection
Variant selection
Manage variants
Manage variants
Save variant
Save variant

Size L (Desktop)

Variant selection
Variant selection
Manage variants
Manage variants
Save variant
Save variant

Layout

The variant management control is merged with the page title (or next to or merged with title of the respective control, such as a table).

Filter Bar (Page Title)

The variant management control is merged with the page title within the page header container, and saves the stored filter settings or both the filter and control settings.

Variant management within the filter bar, merged with the page title
Variant management within the filter bar, merged with the page title

Table

The variant management control can also store control settings like layout, table column visibility, sorting, or grouping independently of the filter settings.

It is either merged with the control title or placed next to it.

If you place the title or variant management control inside a toolbar, apply the following styles:

  • Set the toolbar height to 3 rem.
  • Use a transparent toolbar.
  • Use the title class “sapMH4Fontsize”.
Variant management within the table toolbar
Variant management within the table toolbar

If the table has a separate title, place the title first.

Variant management with table title
Variant management with table title

Behavior and Interaction

This control allows the user to select, create, update, and delete variants for filter settings and control parameters such as layout, table column visibility, sorting and grouping.

Selecting a Variant

The page title displays the active variant. Clicking the title dropdown opens a popover that displays all available variants. The currently active variant is highlighted. To load another variant, the user simply selects one from the list.

Variants that have been modified but not saved are marked with an asterisk(*) on the page title.

Selecting a variant
Selecting a variant

If more than 10 variants exist, a search option is displayed.

Select variant – Search option
Select variant – Search option

The standard variant is the minimum set of filters delivered by SAP, and cannot be modified or deleted.

Save

Save can only be applied to variants that the user is allowed to save. Otherwise, this button is disabled. Save overwrites the active variant.

Save As

Save As enables the user to save the current filter settings as a new variant. The Save As function can also be used to duplicate existing variants for later modification.

Manage

Manage opens a dialog that allows the user to update, delete or favorite/unfavorite existing variants.

Saving & Creating a Variant

The following options can be set:

Set as Default

The variant that is set to default is selected when the user launches the app.

Apply Automatically

If this option is active, the variant is executed immediately when selected. The user does not need to click or tap the Go button. This option is often used if small filter changes need to be made before the user finally executes the search, or if the selection is likely to cause long loading times.

Public

Setting a variant to Public makes it available to other users. A variant can be set to Public by individual users, key users, SAP (default delivery), or partners.

All variants that are set to Public are available within the Manage Views dialog. Users can favorite variants from the pool to add them to their My Views popover, or unfavorite variants to remove them.

Note that variants users create themselves are favorited automatically, while variants created by other users are unfavorited by default.

Save As
Save As

Save as Tile

The user can save the currently selected variant as a tile on the launchpad using the Save as Tile action in the Share menu.

In the Save as Tile dialog, the user can define the tile title and subtitle, a description, and the launchpad group in which the tile should appear.

Save as tile via 'Share' button
Save as tile via 'Share' button
'Save as Tile' dialog
'Save as Tile' dialog

Managing Variants

In the Manage Views dialog, the user can rename, delete, and change properties of existing variants.

Users can only modify or delete entries if they have the necessary permissions. By default, variants that a user has created can also be modified and deleted.

Users cannot modify and delete variants created by other users.
Exception: Key users can also change and delete variants created by others.

Add to Favorites

The My Views popover only shows the variants selected as favorites in the Manage Views dialog. If the user creates a variant, it is selected by default, along with the standard SAP variants. Public variants created by other users are not marked as favorites. This prevents the popover from becoming overcrowded with public variants that are not relevant for the user.

Manage
Manage

Guidelines

Save as Tile:

Use the name of a variant as the title of the application tile. Map this as a preset title that cannot be edited by the user.  In this case, whenever the variant is updated, the tile is updated accordingly.

If the variant has been modified but not yet saved (“dirty state”), ensure that the variant is saved before the tile is created.

Exception: If the variant cannot be referenced directly due to technical limitations, offer the standard tile creation option where filter parameters and settings are only saved within the URL.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation