Intro

The value help dialog is a UI pattern that helps the user search and select single and multiple values. The user can also define conditions.

The value help dialog is generally called from an input field or a multi-input field by clicking the selection icon (value help icon) of the input field.

Clicking the value help icon opens the value help dialog

Clicking the value help icon opens the value help dialog

Usage

Use the value help dialog if:

Do not use the value help dialog if:

information
For more information on which selection control to choose, see the selection control overview.

Responsiveness

The behavior of the value help dialog on a phone differs from its behavior on a tablet or desktop device. Both the navigation and the positioning of the selection area differ depending on the device.

Value help dialog - Sizes L and XL

Value help dialog - Sizes L and XL

Value help dialog - Size M

Value help dialog - Size M

Value help dialog - Size S

Value help dialog - Size S

Components

The value help dialog contains the following components:

1) Header
2) Icon tab bar / list control (phone)
3) Search template (optional)
4) Basic search
5) Go button
6) Result list
7) Selected items and conditions
8) Footer toolbar
9) Filters
10) Area for defining conditions, such as ranges and exclusions

Components of the Value Help Dialog

Value help dialog diagram. components 1-8
Value help dialog diagram, component 9
Value help dialog diagram, component 10

Header (1)

The header bar contains the dialog title. See the Guidelines section below.

Icon Tab Bar / List Control (Phone) (2)

Depending on the device, the following controls are used to display the content of the value help dialog:

Search Template (3)

Search templates allow the user to display different or additional fields in the filter area and result list. Depending on the use case, the user can switch between the different search templates in order to use different fields when searching. For example, the search template “Customer (by Company Code)” displays the additional field “Company Code” in the filter area and result list.

Basic Search (4)

The basic search finds all results that are somehow related to the input. For example, the search term “A” returns all the results containing the letter “A”.

Always offer the basic search in the value help dialog. Position the basic search to the right of the search template control. If there is no search template control, left-align the basic search.

Go Button (5)

The Go button triggers the search and filters the result list.

Result List (6)

Selected Items and Conditions (7)

The selected items and conditions are displayed in a tokenizer (see Token for more information). Each selected item or condition is displayed as one token.

There is no longer a visual difference between included and excluded items and conditions. They are now differentiated using operators (see Using the Filters).

The footer bar offers the OK and Cancel buttons.

Filters (9)

The filter area offers a filter field for each column in the result list. In some cases, there can be specific filter fields that do not have a corresponding column on the UI. These fields typically come from the back-end service. Initially, the filter area is hidden.

Value help dialog - Filters

Value help dialog - Filters

For the basic search with filters, the filter bar (sap.ui.comp.filterbar.FilterBar) is implemented in advanced mode. Advanced mode differs from the basic mode in the following ways:

Always hide the filter area in the value help dialog by default. Only show the filter area by default if the basic search can’t be provided.

Note that the value help icon of the Product ID field in the current value help dialog will open only the Define Conditions screen. The full value help dialog is not shown in order to prevent endless loops. For example, the value help icon of the Product Name or Category field in the value help for a Product field will navigate directly to the Define Conditions: Product screen.

Using the Filters

Users can enter operators (such as “=“) to define the conditions directly within the field without opening the Define Conditions tab.

<div> <div>Operator</div> <div>Input Notation</div> <div>Example</div> </div> <div> <div>between</div> <div>value[…]{color=pink-8}value</div> <div>000 <strong>…</strong> 100</div> </div> <div> <div>equal to</div> <div>[=value]{color=pink-8}</div> <div>=0001</div> </div> <div> <div>contains</div> <div>[*]{color=pink-8}value[*]{color=pink-8}</div> <div>*1*</div> </div> <div> <div>starts with</div> <div>value[*]{color=pink-8}</div> <div>001*</div> </div> <div> <div>ends with</div> <div>[*]{color=pink-8}value</div> <div>*5</div> </div> <div> <div>less than</div> <div>[<]{color=pink-8}value</div> <div><100</div> </div> <div> <div>less than or equal to</div> <div>[<=]{color=pink-8}value</div> <div><=200</div> </div> <div> <div>greater than</div> <div>[>]{color=pink-8}value</div> <div>>0300</div> </div> <div> <div>greater than or equal to</div> <div>[>=]{color=pink-8}value</div> <div>>=0500</div> </div> <div> <div>not between</div> <div><strong>[!(]{color=pink-8}</strong> value[…]{color=pink-8}value <strong>[)]{color=pink-8}</strong></div> <div>!(000 <strong>…</strong> 100)</div> </div> <div> <div>not equal to</div> <div>[!(=]{color=pink-8}value <strong>[)]{color=pink-8}</strong></div> <div>!(=0)</div> </div> <div> <div>does not contain</div> <div>[!(*]{color=pink-8}value[*)]{color=pink-8}</div> <div>!(*1*)</div> </div> <div> <div>does not start with</div> <div>[!(]{color=pink-8}value[*)]{color=pink-8}</div> <div>!(001*)</div> </div> <div> <div>does not end with</div> <div>[!(]{color=pink-8}[*]{color=pink-8}value[)]{color=pink-8}</div> <div>!(*5)</div> </div> <div> <div>not less than</div> <div>[!(<]{color=pink-8}value <strong>[)]{color=pink-8}</strong></div> <div>!(<100)</div> </div> <div> <div>not less than or equal to</div> <div>[!(<=]{color=pink-8}value <strong>[)]{color=pink-8}</strong></div> <div>!(<=200)</div> </div> <div> <div>not greater than</div> <div>[!(>]{color=pink-8}value <strong>[)]{color=pink-8}</strong></div> <div>!(>0300)</div> </div> <div> <div>not greater than or equal to</div> <div>[!(>=]{color=pink-8}value <strong>[)]{color=pink-8}</strong></div> <div>!(>=0500)</div> </div> <div> <div>empty</div> <div><strong>[<empty>]{color=pink-8}</strong></div> <div><empty></div> </div> <div> <div>not empty</div> <div><strong>[!(]{color=pink-8}[<empty>)]{color=pink-8}</strong></div> <div>!(<empty>)</div> </div>
Note:

Depending on the underlying field, the operators may be labeled differently in the Define Conditions area. This doesn’t affect the input notation, which is based on the operator logic and remains constant.

Example: Operators for Date Fields
<div> <div>Operator Label</div> <div>Input Notation</div> </div> <div> <div>before</div> <div><strong>[<]{color=pink-8}</strong> value</div> </div> <div> <div>before or on</div> <div>[<=]{color=pink-8}value</div> </div> <div> <div>after</div> <div>[>]{color=pink-8}value</div> </div> <div> <div>after or on</div> <div>[>=]{color=pink-8}value</div> </div>
style
column-section-1-1, no-footprint
style
column-section-1-1, no-footprint
Users must use the following notation to get results:

Using an operator to filter the result list

Using an operator to filter the result list

Area for Defining Conditions (10)

In the Define Conditions tab, you can use the following operators to define single and multiple conditions:

  • between
  • equal to
  • contains
  • starts with
  • ends with
  • less than
  • less than or equal to
  • greater than
  • greater than or equal to
  • empty
  • not between
  • not equal to
  • does not contains
  • does not start with
  • does not end with
  • not less than
  • not less than or equal to
  • not greater than
  • not greater than or equal to
  • not empty

For convenience, the operators are grouped into two categories: Include and Exclude.

For Boolean attributes, where only two values are available, the operator dropdown in the condition panel is disabled. Users can pick one of the values from the combo box.

You can also use a combo box if the possible values for a condition are fixed. Users can then choose the value they need from the list.

Each condition is displayed as a token in the Selected Items and Conditions tokenizer.

information

The operator dropdown list may not contain all the operators listed above. The type of field value determines which operators are available.

The type of field value also determines how the operators are labeled. For example, if the field is a date field, the operator labels “less than” and “greater than” change to “before” and “after”.

hint
For information on how to manage white space characters (blanks) when users copy and paste text into input controls, see Removing Leading and Trailing White Space.

'Define Conditions' - List of operators

'Define Conditions' - List of operators

Defining a condition for a Boolean attribute

Defining a condition for a Boolean attribute

style
column-section-1-1, no-footprint
style
column-section-1-1, no-footprint

Behavior and Interaction

Basic Search and Filters

Selecting Items and Defining Conditions

Depending on your use case, the value help dialog can offer different selection options:

Users open the value help dialog by clicking the value help icon in the input field. The next steps depend on the use case and form factor (smartphone or desktop/tablet).

The different use cases are described in the sections below.

Select a Single Item (Smartphone)

Tapping the value help icon opens the dialog. As soon as an item is selected, the value help dialog closes automatically.

Single item selection on a smartphone

Single item selection on a smartphone

Select a Single Item (Desktop/Tablet)

Clicking the value help icon opens the value help dialog for single selection. The icon tab bar and the Selected Items and Conditions are hidden. As soon as an item is selected, the value help dialog closes automatically.

Single item selection on a desktop/tablet device

Single item selection on a desktop/tablet device

Define a Single Condition (Smartphone)

Tapping the value help icon opens the Define Condition tab. Users define a condition by choosing the relevant operator and entering the value or values in the corresponding input field(s).

In this example, we have defined a range.

Defining a single condition on a smartphone

Defining a single condition on a smartphone

Define a Single Condition (Desktop/Tablet)

Clicking the value help icon opens the Define Condition tab. Users define a condition by choosing the relevant operator and entering the value or values in the corresponding input field(s).

In this example, we have defined a range.

Defining a single condition (desktop/tablet)

Defining a single condition (desktop/tablet)

Select Multiple Items and Define Multiple Conditions (Smartphone)

Tapping the value help icon displays the start dialog.

  • The Search and Select tab is used to select multiple items.
  • The Define Conditions tab is used to define multiple conditions.
  • The counters in the titles of both tabs represent the number of selected items/defined conditions.

All selected items and conditions are added as tokens to the Selected Items and Conditions (n) field at the bottom of the start dialog. The counter n indicates the combined number of items selected and conditions defined.

Start dialog

Start dialog

Selecting multiple items on a smartphone

Selecting multiple items on a smartphone

Defining multiple conditions (smartphone)

Defining multiple conditions (smartphone)

Filters on a smartphone

Filters on a smartphone

Select Multiple Items and Define Multiple Conditions (Desktop/Tablet)

Clicking the value help icon displays the icon tab bar with the Search and Select and Define Conditions tabs.

  • The Search and Select tab is used to select multiple items
  • The Define Conditions tab is used to define multiple conditions.

All selected items and conditions are added as tokens to the Selected Items and Conditions (n) field at the bottom of the dialog. The counter n indicates the combined number of items selected and conditions defined.

Selecting multiple items and conditions on a desktop

Selecting multiple items and conditions on a desktop

Selecting multiple items and conditions on a desktop

Selecting multiple items and conditions on a desktop

Define Multiple Conditions (Smartphone)

Tapping the value help icon opens the start dialog with the Define Conditions tab.

The selected values are added as tokens to the Selected Conditions at the bottom of the start dialog.

Start dialog

Start dialog

Defining multiple conditions on a smartphone

Defining multiple conditions on a smartphone

Define Multiple Conditions (Desktop/Tablet)

Clicking the value help icon opens the Define Conditions tab.

The selected values are added as tokens to the Selected Conditions at the bottom of the start dialog.

Defining multiple conditions on a desktop

Defining multiple conditions on a desktop

Copying and Pasting Multiple Values

The area for defining conditions allows the user to enter multiple values at once (copied from the clipboard).

Users can paste more than one value into the value input field. In this case, the condition row repeats with the previously selected condition and shows one value per row.

If there is no vertical space for the conditions, vertical scrolling is added to the top of the dialog.

Copying and pasting multiple values

Copying and pasting multiple values

Guidelines

Dialog Title

The dialog title differs depending on the device and whether multiple or single selection is used.

For smartphones:

For tablet and desktop devices:

Filtering

If necessary, also provide value help for fields offered in the filters. However, do not provide the full value help dialog for the ID and description fields of the business object that is being selected. For these two fields, make sure that the value help icon opens only the Define Conditions screen.

For example, in a value help dialog for selecting the customer, do not offer full value help for the Customer ID and Customer Name fields. Instead, try to use the value help in combination with a helpful suggestion.

Constant Parameters

You can use constant parameters to pre-filter suggestion lists, dropdowns, and the value help results list. Users can’t change these parameters.

Do not show parameters with constant values as filterable fields in the filter bar of the value help dialog or in the result table columns. Constant values should not be visible to users in any way.

Elements and Controls

Implementation

Visual Design

Elements and Controls

Implementation