Show TOC

Value Help Based on Foreign Key RelationshipLocate this document in the navigation structure

In this topic, we explain how to provide value help for your Fiori app based on the foreign key associations approach.

Process Overview

The following figure depicts the components involved and the development activites that are required to provide - from scratch - the value help option based on the foreign key relationship.

Providing value help based on foreign key relationship
Figure 1: Providing value help based on foreign key relationship
Modelling Text Views
For implementing the text view, we recommend that you follow these rules:
  • Text views should only be defined for language-dependent texts and are annotated with @ObjectModel.dataCategory: #TEXT.
  • At least one non-key field has to be defined as a text field in a text view. A text field is annotated with @Semantics.text: true
  • The language field that is used in the text view must be a key field.
    • The language field is annotated with @Semantics.language: true.

    • The language code represents the corresponding ABAP internal format (like SPRAS). In particular, do not use external formats/ISO codes!
  • The text view defines a representative key field (a field for which the text view provides texts).
  • The name of the text view ends either with ...Text or ...T.
Defining Relationship to Language-Dependent Texts
  • The relationship between a field and its language-dependent descriptive text field(s) is established by using an annotation @ObjectModel.text.association.

  • The association referenced by @ObjectModel.text.association points to a language- dependent text view. Its cardinality is [0/1..*].
Steps
To provide value help from scratch, proceed as follows:
  1. Create a data definition with a CDS view that serves as text provider

    The following set of CDS annotations is relevant when defining text views:

    The annotations at view level are:

    Annotation and Value

    Effect

    @ObjectModel.dataCategory: #TEXT

    Indicates that the annotated CDS view represents texts (defines a text view)..
    Note One key element is used to specify the language.

    @ObjectModel.representativeKey: '<name>'

    For text views, the <name> identifies the key element to which the text fields refer.

    @Search.searchable: true

    This annotation is necessary to define that the search function is supported.

    The annotations (required) on the field level are:

    Annotation and Value

    Effect

    @Semantics.language: true

    The annotated field identifies the language.

    @Semantics.text: true

    Identifies fields as text fields (fields holding a textual description).

    @Search.defaultSearchElement: true

    Denotes that it is possible to search for the annotated field in the freestyle search field on the value help dialog.

    @Search.fuzzinessThreshold: <value>

    Defines how fuzzy the text search applied to the annotated field should be. For example, the value 0.8 refers to a similarity of 80%.

    Example:

    The listing below implements a sample text view. Its entity is named ZDEMO_I_Text and uses a database table T006A as its data source. Each text field needs to be annotated with @Semantics.text: true. In this example, only the field MSEHT (Name) is displayed as a text field on the value help dialog screen. The annotations @Search.searchable: true and @Search.defaultSearchElement: true are necessary to define that the search function is supported. This means that a freestyle search field appears on the value help UI where it is possible to search for the text field (Name). The annotation @Search.fuzzinessThreshold: 0.8 defines that the text search should be applied to this element with a similarity value of 80%.

      @AbapCatalog.sqlViewName: 'ZDEMO_I_T'
      @ObjectModel.dataCategory: #TEXT
      @ObjectModel.representativeKey: 'UnitOfMeasure'
    						
      @Search.searchable: true
    						
      define view ZDEMO_I_Text  
    		as select from t006a       as TextProvider
      {
    	key TextProvider.msehi          as UnitOfMeasure,
    	@Semantics.language: true       -- identifies the language  
    	key TextProvider.spras          as Language,
    	@Semantics.text: true            -- identifies the text field
    	@Search.defaultSearchElement: true
    	@Search.fuzzinessThreshold: 0.8    
    	TextProvider.mseht              as Name
      }
    						
    					
  2. Create a data definition with a CDS view that serves as value help provider

    The following set of CDS annotations is relevant when defining value help views that serve as consumer of a text view:

    The annotations (required) at view level are:

    Annotation and Value

    Effect

    @Search.searchable: true

    These annotations are necessary to define that the search function is supported.

    @EndUserText.label: '<text>'

    This annotation specifies the heading text that will be visible in the value help dialog.

    The annotations (required) on the field level are:

    Annotation and Value

    Effect

    @ObjectModel.text.association: '<_AssocToTextProvider>'

    Name of an association to a text view, which provides descriptive texts for the annotated field.

    @Search.defaultSearchElement: true

    This annotation denotes that it is possible to search for the annotated field in the freestyle search field on the value help dialog.

    Example:

    In the following example, the CDS view ZDEMO_I_ValueHelp selects the values for the value help from DB table T006. The annotation @EndUserText.label: 'Unit of Measure Value Help' provides a text that will be displayed in the heading of the value help dialog. The annotations @Search.searchable: true and @Search.defaultSearchElement: true are necessary to define that the search function is supported. This means that a freestyle search field appears on the value help UI where it is possible to search in the content of the field UnitOfMeasure and its description. The annotation @ObjectModel.text.association: '_Text' describes an association that points to the text view ZDEMO_I_Text, which contains the text fields to be displayed in the value help dialog.

      @AbapCatalog.sqlViewName: 'ZDEMO_I_VH'
      @Search.searchable: true
      @EndUserText.label: 'Unit of Measure Value Help'
    	
      define view ZDEMO_I_ValueHelp 
    	as select from t006     as ValueProvider 
    	
    	association [0..*] to ZDEMO_I_Text as _Text
    		on $projection.UnitOfMeasure = _Text.UnitOfMeasure
      {
    	@ObjectModel.text.association: '_Text'
    	@Search.defaultSearchElement: true
    	key msehi   as UnitOfMeasure,
    	
    	-- association 
    	_Text
      }
    	
    
  3. Assign the value help to the relevant field of the consumer view

    To enable value help in the Fiori app, the following two additions in the consumer view are required:

    a. First, add the association to the value help provider view that contains the value list.

    b. Then add the annotation @ObjectModel.foreignKey.association to the field for which a value help should be made available.

    The annotation (required) on the field level:

    Annotation and Value

    Effect

    @ObjectModel.foreignKey.association: '<_AssocToValueHelpProvider>'

    The annotation assigns the association ‘_AssocToValueHelpProvider’ to the given view field: The association’s target view serves as a value help provider and is used to retrieve the values of the value help.
    Note The maximum target cardinality of the association has to be 1.
    More on this: ObjectModel Annotations

    Example:

    The consumer view ZDEMO_C_ValueHelp_Demo in the listing below defines a data model for sales order items. Here, the association _QuantityUnitValueHelp with the target view that represents a value list for quantity units (ZDEMO_I_ValueHelp) is also defined. This association defines a foreign key relationship for the annotated field Document.QuantityUnitCode. At runtime, the annotated field must be valuated as equal to the annotated representative key element of the target view.

      ...
    	
      define view ZDEMO_C_ValueHelp_Demo
    	     as select from SalesOrderItem as Document
    	
    	/* Association to quantity unit value help provider */
    	association [0..1] to ZDEMO_I_ValueHelp as _QuantityUnitValueHelp
    	     on $projection.QuantityUnitCode = _QuantityUnitValueHelp.UnitOfMeasure
    	...
      { 
    	
    	/* Field list */
    	...
    	@Semantics.unitOfMeasure: true
    	@ObjectModel.foreignKey.association: '_QuantityUnitValueHelp'
    	Document.QuantityUnitCode,   
    	...
    	/* List of associations */
    	...
    	_QuantityUnitValueHelp
      }
    	
    
  4. Expose the value help as OData service

    Create either an OData service automatically by adding the annotation @OData.publish: true into the consumer view or manually using the SEGW transaction. In the latter case, you must expose the association to the value help provider view.

    More on this: Generating an OData Service Based on a CDS View
Results

If you run the sales order app, the annotated input field displays a value help icon.

Value help is assigned to the Unit of Measure input field
Figure 2: Value help is assigned to the Unit of Measure input field

When you call the value help dialog, it displays the key and text fields that are specified in the value help text view

Value help dialog that results from the foreign key relationship
Figure 3: Value help dialog that results from the foreign key relationship
Remember The foreign key-based value help can be redefined by defining a modeled value help view. The field that should be equipped with the specific value help has to be annotated with @Consumption.valueHelp. More on this: Value Help Based on Modelled View