Using Annotations to Configure Fiori Elements Applications

In this piece we will continue on to implementing a search help for our Smart Filter Bar filters along with setting up Multi-Combobox and Date Range Selection controls.

Example 3: Configuring the Search Help of a Smart Control

It is expected to provide functionality to assist the end-user with choices or ranges with which to set filter values to restrict OData service calls. So, let’s configure a search help for our Contract Type filter.

To configure this search help we will turn again to our local annotation file and make a few changes using the SAP Common vocabulary’s ValueList term as follows:

Vocabulary Annotation Example for Defining a Search Help

Here we are mapping a local property to a property returned from the SH_ContractTypeSet search help endpoint and are also displaying to the user the Description property from this service to give the user more information about the contract type they are selecting. We have set the SearchSupported to “true” to provide a modal search help for the Contract Type filter. Please note that we will be making changes to this set of annotations in the next example when we remove the search help and, instead, tell the application to render our filter as a Multi-Combobox with fixed-values.

Now, when we click on the search help icon to the right of our input field, we get the following (after performing a search):

These examples use arbitrary mock data generated within the Web IDE.

Example 4: Setting the Smart Control to a Render as a Multi-Combobox

What we see above is a Multi-Input Field control with an associated search help and what we require is a Multi-Combobox so we’re going to have to return to the ABAP layer and make some changes to how the EDMX metadata model for our service is generated. Specifically, we want to target the DEFINE method within the services model provider extension class. This allows us to get a hold of the service’s model (/IWBEP/IF_MGW_ODATA_MODEL) that has methods that allow for manipulation of the metadata model including SAP annotations. We are specifically looking to add the value-list SAP annotation and set its value to “fixed-values”.  Doing so will give us the result we seek.

A form-based example of what that class would look like is illustrated below:

We will now redefine the DEFINE method of our model provider extension class and add code like what is displayed below:

  "Method-local declarations:
  DATA lo_entity_type   TYPE REF TO /iwbep/if_mgw_odata_entity_typ.
  DATA lo_property      TYPE REF TO /iwbep/if_mgw_odata_property.
  DATA lo_annotation    TYPE REF TO /iwbep/if_mgw_odata_annotation.

  "Call parent:
  super->define( ).

  "Set the appropriate annotations for each property of the Contract entity:
  lo_entity_type = io_odata_model->get_entity_type( 'Contract' ).
  IF lo_entity_type IS NOT INITIAL.

    "Set ContractType as fixed-value list:
    lo_property = lo_entity_type->get_property( iv_property_name = 'ContractType' ).
    IF lo_property IS NOT INITIAL.

      lo_annotation = lo_property->/iwbep/if_mgw_odata_annotatabl~create_annotation( /iwbep/if_mgw_med_odata_types=>gc_sap_namespace ).
      lo_annotation->add( iv_key = 'value-list' iv_value = 'fixed-values' ).

    ENDIF.

  ENDIF.

When complete our service will now append the sap:value-list=”fixed-values” annotation and value to the ContractType property of our OData service’s metadata model.

Now, when we refresh our application, we have what looks to be a Multi-Combobox. Although this was our goal, we do require that a more user-friendly description be shown to the user and, when chosen, the actual value (displayed currently) be applied as a filter to any subsequent search.

So now we need to focus on the search help endpoint (in example 3 above, this was the SH_ContractTypeSet entity set). Using similar code that was illustrated above when adding the sap:value-list=”fixed-values” annotation to our ContractType property on the Contract entity type of our main service, we are going to do something similar to our contract type set collection.

Again, in the DEFINE method of our model provider extension class for our search help service where the SH_ContractTypeSet entity set lives, we will implement the following code:

  "Method-local declarations:
  DATA lo_annotation    TYPE REF TO /iwbep/if_mgw_odata_annotation.
  DATA lo_entity_type   TYPE REF TO /iwbep/if_mgw_odata_entity_typ.
  DATA lo_property      TYPE REF TO /iwbep/if_mgw_odata_property.

  "Call parent:
  super->define( ).

  "Set the appropriate annotations for each property of the SH_ContractType entity:
  lo_entity_type = model->get_entity_type( 'SH_ContractType' ).

  IF lo_entity_type IS NOT INITIAL.

    "Set description to be displayed for the ContractType value:
    lo_property = lo_entity_type->get_property( iv_property_name = 'ContractType' ).
    IF lo_property IS NOT INITIAL.
      
      lo_annotation = lo_property->/iwbep/if_mgw_odata_annotatabl~create_annotation( /iwbep/if_mgw_med_odata_types=>gc_sap_namespace ).
      lo_annotation->add( iv_key = 'text' iv_value = 'Description' ).

    ENDIF.

  ENDIF.

With that change, the set of options within the Multi-Combobox will now render as follows:

Example 5: Setting a Date Range Filter

We are now going to add the ContractValidTo property to our list of default filters for our application. This field is of type Edm.DateTime and by making a change to our local annotation file, we will now see it appear within the smart filter bar of our Fiori Elements application:

Adding ContractValidTo as a Default Filter

Once complete, we now have a new filter at the top of our application that allows for us to input a date and time. We may hope that, through the magic of Fiori Elements and the underlying smart controls, we would be provided the necessary input to interact with it (Date/Time Picker) due to the nature of this field’s entity data model type. However, as of the time of this writing, it does not look like we have the option of a Date/Time Picker to be rendered within the Smart Filter Bar of our application unless we extend it ourselves. We will probably see an enhancement of this nature in a future release of SAPUI5.

Instead, we just want the user to work with the date portion of this DateTime field so we will enhance it with the SAP annotation of display-format=”Date”. This is essentially stripping the time from the Edm.DateTime value and allowing it to now function within the scope of SAPUI5 Date Picker control. The code is implemented very much in the same way as presented above and, once complete, we have the following:

Everything looks good but we require that the user may select a range of dates and would rather them not go through the trouble of clicking the search help icon, selecting a date and then clicking OK. We can append another SAP annotation to the ContractValidTo property of the Contract entity to accomplish this (filter-restriction=”interval”):

We now have a Date Range Selection control that allows for a range of dates to be applied as a filter directly from the Smart Filter Bar (without a search help).

What’s Next

I certainly hope that this was helpful and gave you some insight into the power of Fiori Elements. I hope to continue this series by digging into configuring and extending the list report’s smart table along with working with the list report floorplan’s API to call OData function imports that act on ranges of selected table data.

For other articles in this series, please refer to the list below:

• Annotating and Extending Fiori Element Applications
• Annotating and Extending Fiori Element Applications: List Report Part 1 (Smart Filter Bar Configuration)
• Annotating and Extending Fiori Element Applications: List Report Part 2 (Smart Filter Bar Configuration Continued)
• Annotating and Extending Fiori Element Applications: List Report Part 3 (Smart Table Configuration)

Some Resources to Consider

• Using OData Analytics in SADL-Based Services
• SAP – ABAP Programming Model for SAP Fiori
• SAP Annotations for OData Version 2.0
• List Report (SAP Fiori Element)
• Vocabulary-Based Annotations
• OData 4.0 Vocabularies – SAP UI
• OData 4.0 Vocabularies – SAP Common
• Overview (OData Version 2.0)
• Fiori Elements – Why cookie cutters make me happy
• Fiori Elements – How to Develop a List Report – Using Local Annotations
• com.sap.vocabularies.Common.v1.xml
• com.sap.vocabularies.UI.v1.xml