Using Annotations to Configure Fiori Elements Applications

joe_rupert · ‎03-02-2017

Using Annotations to Configure Fiori Elements Applications

My goal here is to outline some common requirements when building applications with Fiori Elements. I will not be covering how to work with the SAP Web IDE’s annotation modeler or how to configure some of the initial properties of your application because this has already been covered in other articles.

The context of the examples that follow are listed below:

These examples will be presented in an application that relies on a local vocabulary-based annotation file and not one that is generated via a service (although these vocabulary annotations could originate from a separate source or be a part of the OData service metadata model/EDMX). SAP annotations will be added via configuration within Gateway (SEGW) or programmatically within the ABAP layer via our service’s generated model provider extension class artifact (<service>_MPC_EXT).

I am also building the client-side code for this example in the SAP Web IDE so the screenshots contained within may reflect that development environment.

Although this application could be leveraging SAP’s Service Adaptation Definition Language (SADL) and Core Data Services (CDS) Views to rapidly create a Fiori Elements application (and I recommend this if possible), the purpose of this article is to outline how annotations affect/shape Fiori Elements and the smart controls therein regardless of their origin. I will not be covering CDS View development with annotations (modularized or not) or separation of concerns issues. For more information on these topics, please visit this article by Jocelyn Dart of SAP.

Configuring the Smart Filter Bar in a Fiori Elements List Report Floorplan

So now that we have had a brief primer on Fiori Elements and SAP and vocabulary-based annotations in OData, it is time to put them to use to configure filters within a List Report Floorplan. We will walk through the steps necessary to specify default filters, configure search helps and set fixed-value Multi-Combobox and Date Range Selection controls.

Example 1: Setting a Default Filterable Field

Let’s begin by first setting up a few filterable fields for our application. To do so, we will need to configure some properties that belong to our entity type (Contract in this case) within SAP Gateway (transaction: SEGW). This change will remove the sap:filterable=”false” SAP annotation from our metadata model (EDMX output from the service) and allow for these field to appear as an option to filter our data in the List Report floorplan application.

So far so good but we would like to also specify that this particular field is one of our out-of-the-box default filter criteria so it appears at the top of our List Report when the application initially launches. This will require a change within our local annotation file that targets the main entity (Contract) whose set is being displayed in the application. We are going to define an annotation with an attribute (Term) whose value is going to be set to UI.SelectionFields. Under this XML element of our local annotation file, we will specify a collection of property paths within the Contract entity. This collection will define our default filters.

So, without having defined any other annotations, we are left with the following within our Smart Filter Bar:

Example 2: Setting Up Basic Search

You may have noticed above that we had an extra input within the Smart Filter Bar area of our application (with the “Search” watermark and a magnifying glass icon floated right). This is not present by default but is, instead, configured via a SAP annotation at the level of the entity set. In Gateway (SEGW), we will open our service and expand the Data Model > Entity Sets and find our ContractSet where we will configure this entity set to be searchable as follows:

This change will add the following sap:searchable=”true” to the ContractSet entity set within the EntityContainer of our service metadata model and enable the Basic Search for the application.

The benefit of adding the Basic Search to your application is that you can define a search across multiple fields of an entity. To do so, you will either need to implement code to handle the query string via the IO_TECH_REQUEST_CONTEXT->GET_SEARCH_STRING (/IWBEP/IF_MGW_REQ_ENTITYSET) method from the importing parameter of the <EntitySet>_GET_ENTITYSET method of your data provider extension class. I would recommend leveraging this context and not utilizing any deprecated APIs/parameters (usually flagged as “obsolete”).

If you are using SADL to map your service’s data source to a CDS View, your life gets a lot easier. When establishing your service implementation mapping for your entity set by mapping it to a CDS View data source via SADL, your data provider extension class now has some new methods it implements that allow you to plug into the framework to expedite some of your development. We want to focus on the SET_QUERY_OPTIONS method of the IF_SADL_GW_QUERY_CONTROL interface.

This method allows us to do a quite a few things by leveraging its IO_QUERY_OPTIONS (IF_SADL_GW_QUERY_OPTIONS) importing parameter. We can set input parameters for our CDS Views, map authorization objects to our returning fields, get and set/modify requested fields, set our sorting order and, of course, define our search scope.

An example is presented below:

  "Method-local data declarations:



  DATA lt_search_scope  TYPE        if_sadl_public_types=>tt_search_scope.



  CASE iv_entity_set.



    WHEN 'ContractSet'.



      "Set basic search scope to include the following fields:

      lt_search_scope = VALUE #( ( `CONTRACT_NUM` ) ( `CONTRACT_TYPE` )

      ( `CONTRACT_NET` ) ( `CONTRACT_ADMIN` ) ).



      io_query_options->set_text_search_scope( lt_search_scope ).



  ENDCASE.

In the next section we will discuss creating search helps for Smart Filter Bar controls along with converting these controls into Multi-Combobox, Date Picker and Date Range Picker controls.

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