Skip to content

Value Help

The UI5 Antares library includes a built-in value help class that can be used in conjunction with the Entry Create and Entry Update classes, or as a standalone component with any sap.m.Input control within a SAPUI5 application.

Attention

Please be advised that the Value Help class is only available for the SIMPLE Form when it is used in conjunction with the Entry Create and Entry Update classes. Should you require further information, please refer to the Form Type section.

Features

1) The sap.ui.comp.valuehelpdialog.ValueHelpDialog is generated with a table and filter bar consisting of the EntitySet properties defined in the class constructor.

2) The Value Help class is responsible for managing the search functionality accessible via the filter bar or search field.

3) The Value Help class is responsible for writing the selected value from the table into the input field.

4) The Value Help class enables the initial filters to be applied when the Value Help Dialog is first initiated.

5) The Value Help class enables users to attach a function that will be triggered immediately upon opening the dialog or selecting a value from the table.

Warning

Please note that the Value Help class only supports a single selection.

Info

The ValueHelpCL class offers all its features for both entry class-integrated (Entry Create/Entry Update) and standalone usage, even if they are not shown in the examples.

Constructor

You must initialize an object from ValueHelpCL class in order to use it.

Parameter Type Mandatory Default Value Description
controller sap.ui.core.mvc.Controller Yes The controller object (usually this)
settings object Yes
    propertyName string Yes This is the property of the entity for which the value help is being created.
    valueHelpEntity string Yes This is the name of the EntitySet that will be bound to the table in the Value Help Dialog
    valueHelpProperty string Yes Once a selection has been made in the table, this parameter defines the property of the valueHelpEntity to be used for setting the value of the property defined in the propertyName parameter.
    readonlyProperties? string[] No [] The properties of the valueHelpEntity that are displayed in the columns of the table
    excludedFilterProperties? string[] No [] The properties of the valueHelpEntity that are excluded from the filter bar
    title? string No ${valueHelpEntity} The title of the Value Help Dialog
    searchPlaceholder? string No Search ${valueHelpEntity} The placeholder in the search field of the Value Help Dialog
    namingStrategy? NamingStrategies No CAMEL_CASE The naming strategy that is used to generate the labels for filter bar and table column headers
    resourceBundlePrefix? string No antaresVH The resource bundle prefix that is used for the i18n text lookup
    useMetadataLabels? boolean No false Indicates whether the labels should be derived from the metadata to be used in the filter bar and table column headers
    filterModelName? string No UI5AntaresVHFilterModel The JSONModel name of the filter bar which is needed by the ValueHelpCL class
    filterCaseSensitive? boolean No false Set to true for case sensitive search in the filterbar
modelName? string No undefined The name of the OData V2 model. Leave this parameter undefined if the name of the OData model = "" (empty string)

Dialog Generation Process

The following steps outline the process followed by the ValueHelpCL class when creating the Value Help Dialog.

1) The ValueHelpCL class is responsible for creating a table and assigning the settings.valueHelpProperty as the first column within the table.

2) The ValueHelpCL class adds all the properties specified in the settings.readonlyProperties array as columns to the table adjacent to the first column.

3) The ValueHelpCL class is responsible for binding the EntitySet specified in the settings.valueHelpEntity to the newly created table.

4) The ValueHelpCL class is responsible for creating a filter bar and UI controls (sap.m.Input, sap.m.DatePicker, etc.) for the properties specified through the settings.valueHelpProperty and settings.readonlyProperties parameters. It should be noted that the properties defined in the settings.excludedFilterProperties are not included in the filter bar.

5) The ValueHelpCL class is responsible for creating a JSONModel to facilitate the filter bar.

6) The ValueHelpCL class is responsible for creating a search field.

7) The ValueHelpCL class utilizes internal functions to facilitate the selection and filter bar search.

Tip

By default, all properties specified through the readonlyProperties parameter are included in the filter bar. To exclude properties from the filter bar, use the excludedFilterProperties parameter. Please note that properties excluded from the filter bar will still be visible in the table of the Value Help Dialog.

Attention

The key property specified in the valueHelpProperty parameter cannot be excluded from the filter bar.

Label Generation

The ValueHelpCL class employs the same methodology as that defined in Label Generation section for the generation of labels for table column headers and filter bar elements. Please refer to the list below for settings that can be applied in different label generation scenarios.

Scenario 1: To enable the use of labels defined in the OData metadata, please set the settings.useMetadataLabels parameter to true.

Scenario 2: To utilize i18n labels on the label generation, you have two options:

  1. Use the default format (antaresVH + valueHelpEntity + propertyName) for the text keys in your i18n file.
  2. Modify the prefix by using the settings.resourceBundlePrefix parameter.

Scenario 3: In order for the library to generate labels from the technical property names of the EntitySet that is defined, it is necessary to set the correct value for the settings.namingStrategy parameter.

Example

We will consider the following scenario: You have an EntitySet named Products with the following properties: ID, name, categoryID, and supplierID. You also have other EntitySets named Suppliers and Categories, which you intend to use as a value help for the Products-supplierID and Products-categoryID properties.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
import Controller from "sap/ui/core/mvc/Controller";
import EntryCreateCL from "ui5/antares/entry/v2/EntryCreateCL"; // Import the class
import ValueHelpCL from "ui5/antares/ui/ValueHelpCL"; // Import the Value Help class
import { FormTypes } from "ui5/antares/types/entry/enums"; // Import the FormTypes enum

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  public async onCreateProduct() {
    const entry = new EntryCreateCL(this, "Products");

    // Create an object from the ValueHelpCL class
    const categoryVH = new ValueHelpCL(this, {
        propertyName: "categoryID", // This is the property of the Products entity
        valueHelpEntity: "Categories", // This is the entity set that provides data
        valueHelpProperty: "ID", // This is the property of the entity set that will be mapped to propertyName after the selection is made
        readonlyProperties: ["name"] // These properties will be the columns of the table on the Value Help Dialog
    });

    // Create an object from the ValueHelpCL class
    const supplierVH = new ValueHelpCL(this, {
        propertyName: "supplierID", // This is the property of the Products entity
        valueHelpEntity: "Suppliers", // This is the entity set that provides data
        valueHelpProperty: "ID", // This is the property of the entity set that will be mapped to propertyName after the selection is made
        readonlyProperties: [ // These properties will be the columns of the table on the Value Help Dialog
          "companyName",
          "contactName",
          "contactTitle",
          "country",
          "city",
          "paymentTerms"  
        ],
        excludedFilterProperties: ["contactName"] // These properties will be excluded from the filterbar
    });    

    // Set the form type to SIMPLE to be able to use Value Help feature
    entry.setFormType(FormTypes.SIMPLE);

    // Add the value help object for categoryID
    entry.addValueHelp(categoryVH);

    // Add the value help object for supplierID
    entry.addValueHelp(supplierVH);

    entry.createNewEntry(); 
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/entry/v2/EntryCreateCL", // Import the class
    "ui5/antares/ui/ValueHelpCL", // Import the Value Help class
    "ui5/antares/types/entry/enums" // Import the enums
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, EntryCreateCL, ValueHelpCL, EntryEnums) {
      "use strict";

      // Destructure the object to retrieve the FormTypes enum
      const { FormTypes } = EntryEnums;

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        onCreateProduct: async function () {
          const entry = new EntryCreateCL(this, "Products");

          // Create an object from the ValueHelpCL class
          const categoryVH = new ValueHelpCL(this, {
              propertyName: "categoryID", // This is the property of the Products entity
              valueHelpEntity: "Categories", // This is the entity set that provides data
              valueHelpProperty: "ID", // This is the property of the entity set that will be mapped to propertyName after the selection is made
              readonlyProperties: ["name"] // These properties will be the columns of the table on the Value Help Dialog
          });

          // Create an object from the ValueHelpCL class
          const supplierVH = new ValueHelpCL(this, {
              propertyName: "supplierID", // This is the property of the Products entity
              valueHelpEntity: "Suppliers", // This is the entity set that provides data
              valueHelpProperty: "ID", // This is the property of the entity set that will be mapped to propertyName after the selection is made
              readonlyProperties: [ // These properties will be the columns of the table on the Value Help Dialog
                "companyName",
                "contactName",
                "contactTitle",
                "country",
                "city",
                "paymentTerms"  
              ],
              excludedFilterProperties: ["contactName"] // These properties will be excluded from the filterbar
          });    

          // Set the form type to SIMPLE to be able to use Value Help feature
          entry.setFormType(FormTypes.SIMPLE);

          // Add the value help object for categoryID
          entry.addValueHelp(categoryVH);

          // Add the value help object for supplierID
          entry.addValueHelp(supplierVH);

          entry.createNewEntry(); 
        }
      });

    });

Value Help

categoryID supplierID
Value Help Value Help

Attach After Select

It is possible to attach a function that will be executed after the user selects a row in the Value Help Dialog table.

If the ValueHelpCL class is able to retrieve the object from the selected row, it will be passed as a parameter to the attached function. Otherwise, only the value of the valueHelpProperty will be passed as a parameter.

To attach a function, the attachAfterSelect() method can be utilized.

Setter (attachAfterSelect)

Parameter Type Mandatory Description
afterSelect (data: string | object) => void Yes The function that will be executed after the selection
listener? object No The default listener is the controller from constructor

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
import Controller from "sap/ui/core/mvc/Controller";
import ValueHelpCL from "ui5/antares/ui/ValueHelpCL"; // Import the Value Help class
import { Input$ValueHelpRequestEvent } from "sap/m/Input"; // Import the Value Help Request event type

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  // The parameter type should be Input$ValueHelpRequestEvent
  public async onValueHelpRequest(event: Input$ValueHelpRequestEvent) {

    // Create an object from the ValueHelpCL class
    const supplierVH = new ValueHelpCL(this, {
        propertyName: "STANDALONE", // Since this is a mandatory param and not relevant for the standalone usage, you can set anything
        valueHelpEntity: "Suppliers", // This is the entity set that provides data
        valueHelpProperty: "ID", // This is the property of the entity set whose value will be set to the input
        readonlyProperties: [ // These properties will be the columns of the table on the Value Help Dialog
          "companyName",
          "contactName",
          "contactTitle",
          "country",
          "city",
          "paymentTerms"  
        ],
        excludedFilterProperties: ["contactName"] // These properties will be excluded from the filterbar
    });

    // attach the function
    supplierVH.attachAfterSelect(this.afterVHSelect, this);

    // Pass the Input$ValueHelpRequestEvent to the public openValueHelpDialog method.
    supplierVH.openValueHelpDialog(event);
  }

  private afterVHSelect(data: string | object) {
    // here do the logic after the vh selection
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/ui/ValueHelpCL" // Import the Value Help class
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, ValueHelpCL) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        onValueHelpRequest: async function (event) {
          // Create an object from the ValueHelpCL class
          const supplierVH = new ValueHelpCL(this, {
              propertyName: "STANDALONE", // Since this is a mandatory param and not relevant for the standalone usage, you can set anything
              valueHelpEntity: "Suppliers", // This is the entity set that provides data
              valueHelpProperty: "ID", // This is the property of the entity set whose value will be set to the input
              readonlyProperties: [ // These properties will be the columns of the table on the Value Help Dialog
                "companyName",
                "contactName",
                "contactTitle",
                "country",
                "city",
                "paymentTerms"  
              ],
              excludedFilterProperties: ["contactName"] // These properties will be excluded from the filterbar
          });    

          // attach the function
          supplierVH.attachAfterSelect(this._afterVHSelect, this);

          // Pass the event to the public openValueHelpDialog method.
          supplierVH.openValueHelpDialog(event);
        },

        _afterVHSelect: function (data) {
          // here do the logic after the vh selection
        }
      });

    });

Attach After Dialog Opened

It is possible to attach a function that will be executed after the value help dialog is opened.

The generated Value Help Dialog object will be passed as a parameter to the attached function.

To attach a function, the attachAfterDialogOpened() method can be utilized.

Setter (attachAfterDialogOpened)

Parameter Type Mandatory Description
afterDialogOpened (dialog: ValueHelpDialog) => void Yes The function that will be executed after the value help dialog is opened
listener? object No The default listener is the controller from constructor

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
import Controller from "sap/ui/core/mvc/Controller";
import ValueHelpCL from "ui5/antares/ui/ValueHelpCL"; // Import the Value Help class
import { Input$ValueHelpRequestEvent } from "sap/m/Input"; // Import the Value Help Request event type
import ValueHelpDialog from "sap/ui/comp/valuehelpdialog/ValueHelpDialog"; // Import the ValueHelpDialog class

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  // The parameter type should be Input$ValueHelpRequestEvent
  public async onValueHelpRequest(event: Input$ValueHelpRequestEvent) {

    // Create an object from the ValueHelpCL class
    const supplierVH = new ValueHelpCL(this, {
        propertyName: "STANDALONE", // Since this is a mandatory param and not relevant for the standalone usage, you can set anything
        valueHelpEntity: "Suppliers", // This is the entity set that provides data
        valueHelpProperty: "ID", // This is the property of the entity set whose value will be set to the input
        readonlyProperties: [ // These properties will be the columns of the table on the Value Help Dialog
          "companyName",
          "contactName",
          "contactTitle",
          "country",
          "city",
          "paymentTerms"  
        ],
        excludedFilterProperties: ["contactName"] // These properties will be excluded from the filterbar
    });

    // attach the function
    supplierVH.attachAfterDialogOpened(this.afterVHOpened, this);

    // Pass the Input$ValueHelpRequestEvent to the public openValueHelpDialog method.
    supplierVH.openValueHelpDialog(event);
  }

  private afterVHOpened(dialog: ValueHelpDialog) {
    // here do the logic after the vh is opened
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/ui/ValueHelpCL" // Import the Value Help class
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, ValueHelpCL) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        onValueHelpRequest: async function (event) {
          // Create an object from the ValueHelpCL class
          const supplierVH = new ValueHelpCL(this, {
              propertyName: "STANDALONE", // Since this is a mandatory param and not relevant for the standalone usage, you can set anything
              valueHelpEntity: "Suppliers", // This is the entity set that provides data
              valueHelpProperty: "ID", // This is the property of the entity set whose value will be set to the input
              readonlyProperties: [ // These properties will be the columns of the table on the Value Help Dialog
                "companyName",
                "contactName",
                "contactTitle",
                "country",
                "city",
                "paymentTerms"  
              ],
              excludedFilterProperties: ["contactName"] // These properties will be excluded from the filterbar
          });    

          // attach the function
          supplierVH.attachAfterDialogOpened(this._afterVHOpened, this);

          // Pass the event to the public openValueHelpDialog method.
          supplierVH.openValueHelpDialog(event);
        },

        _afterVHOpened: function (dialog) {
          // here do the logic after the vh is opened
        }
      });

    });

Initial Filter Values

It is possible to set initial filter values that will be applied to the Value Help EntitySet when the Value Help Dialog is opened.

Attention

The properties included in the initial filter must either be equal to the valueHelpProperty or included in the readonlyProperties array. Any properties included in the excludedFilterProperties array will be ignored in the initial filter.

To set the initial filter values, the setInitialFilters() method can be utilized.

Setter (setInitialFilters)

Parameter Type Mandatory Description
filters IValueHelpInitialFilter[] Yes The initial filter values

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
import Controller from "sap/ui/core/mvc/Controller";
import ValueHelpCL from "ui5/antares/ui/ValueHelpCL"; // Import the Value Help class
import { Input$ValueHelpRequestEvent } from "sap/m/Input"; // Import the Value Help Request event type

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  // The parameter type should be Input$ValueHelpRequestEvent
  public async onValueHelpRequest(event: Input$ValueHelpRequestEvent) {

    // Create an object from the ValueHelpCL class
    const supplierVH = new ValueHelpCL(this, {
        propertyName: "STANDALONE", // Since this is a mandatory param and not relevant for the standalone usage, you can set anything
        valueHelpEntity: "Suppliers", // This is the entity set that provides data
        valueHelpProperty: "ID", // This is the property of the entity set whose value will be set to the input
        readonlyProperties: [ // These properties will be the columns of the table on the Value Help Dialog
          "companyName",
          "contactName",
          "contactTitle",
          "country",
          "city",
          "paymentTerms"  
        ],
        excludedFilterProperties: ["contactName"] // These properties will be excluded from the filterbar
    });

    // set the initial filters
    supplierVH.setInitialFilters([{
      propertyName: "companyName",
      value: "ABC"
    }, {
      propertyName: "country",
      value: "TR"
    }]);

    // Pass the Input$ValueHelpRequestEvent to the public openValueHelpDialog method.
    supplierVH.openValueHelpDialog(event);
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/ui/ValueHelpCL" // Import the Value Help class
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, ValueHelpCL) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        onValueHelpRequest: async function (event) {
          // Create an object from the ValueHelpCL class
          const supplierVH = new ValueHelpCL(this, {
              propertyName: "STANDALONE", // Since this is a mandatory param and not relevant for the standalone usage, you can set anything
              valueHelpEntity: "Suppliers", // This is the entity set that provides data
              valueHelpProperty: "ID", // This is the property of the entity set whose value will be set to the input
              readonlyProperties: [ // These properties will be the columns of the table on the Value Help Dialog
                "companyName",
                "contactName",
                "contactTitle",
                "country",
                "city",
                "paymentTerms"  
              ],
              excludedFilterProperties: ["contactName"] // These properties will be excluded from the filterbar
          });    

          // set the initial filters
          supplierVH.setInitialFilters([{
            propertyName: "companyName",
            value: "ABC"
          }, {
            propertyName: "country",
            value: "TR"
          }]);

          // Pass the event to the public openValueHelpDialog method.
          supplierVH.openValueHelpDialog(event);
        }
      });

    });

IValueHelpInitialFilter Type Definition

Property Type Description
IValueHelpInitialFilter object
    propertyName string The property name
    value string | number | boolean | Date The filter value of the property

Standalone Usage

The ValueHelpCL class can also be utilized as a standalone component for any sap.m.Input control within a SAPUI5 application.

Note

All of the aforementioned features are also available for standalone use.

Example

Let us consider a scenario in which a sap.m.Input is present on an XML View. The objective is to create a Value Help Dialog when the valueHelpRequest event is triggered by the end user.

Value Help

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import Controller from "sap/ui/core/mvc/Controller";
import ValueHelpCL from "ui5/antares/ui/ValueHelpCL"; // Import the Value Help class
import { Input$ValueHelpRequestEvent } from "sap/m/Input"; // Import the Value Help Request event type

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  // The parameter type should be Input$ValueHelpRequestEvent
  public async onValueHelpRequest(event: Input$ValueHelpRequestEvent) {

    // Create an object from the ValueHelpCL class
    const supplierVH = new ValueHelpCL(this, {
        propertyName: "STANDALONE", // Since this is a mandatory param and not relevant for the standalone usage, you can set anything
        valueHelpEntity: "Suppliers", // This is the entity set that provides data
        valueHelpProperty: "ID", // This is the property of the entity set whose value will be set to the input
        readonlyProperties: [ // These properties will be the columns of the table on the Value Help Dialog
          "companyName",
          "contactName",
          "contactTitle",
          "country",
          "city",
          "paymentTerms"  
        ],
        excludedFilterProperties: ["contactName"] // These properties will be excluded from the filterbar
    });    

    // Pass the Input$ValueHelpRequestEvent to the public openValueHelpDialog method.
    supplierVH.openValueHelpDialog(event);
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/ui/ValueHelpCL" // Import the Value Help class
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, ValueHelpCL) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        onValueHelpRequest: async function (event) {
          // Create an object from the ValueHelpCL class
          const supplierVH = new ValueHelpCL(this, {
              propertyName: "STANDALONE", // Since this is a mandatory param and not relevant for the standalone usage, you can set anything
              valueHelpEntity: "Suppliers", // This is the entity set that provides data
              valueHelpProperty: "ID", // This is the property of the entity set whose value will be set to the input
              readonlyProperties: [ // These properties will be the columns of the table on the Value Help Dialog
                "companyName",
                "contactName",
                "contactTitle",
                "country",
                "city",
                "paymentTerms"  
              ],
              excludedFilterProperties: ["contactName"] // These properties will be excluded from the filterbar
          });    

          // Pass the event to the public openValueHelpDialog method.
          supplierVH.openValueHelpDialog(event);
        }
      });

    });