Generating a User interface

Objectives
After completing this lesson, you will be able to:

After completing this lesson, you will be able to:

  • Generate a User Interface (UI) using SAP Fiori Elements

Generate a User Interface Using SAP Fiori Elements

Introduction

An SAP Fiori Elements (FE) app is an application that uses SAPUI5, its controls, and its Model View Controller (MVC) concepts. Most of the code of an SAP FE app is outside the project, managed centrally by the SAP FE team. The code inside a project only references these central components, which take care of creating the UI according to the latest SAP Fiori design guidelines and covers all the controller logic for you out of the box. The UI can be influenced by OData annotations. They determine, for example, which properties of an OData service make up the columns of a table that displays the content of the service.

Exercise Options

You can perform this exercise in two ways:

  1. Live Environment – using the instructions provided below, you can perform the tasks in the SAP BTP Free Tier account
  2. Platform Simulation – follow the step-by-step instructions within the simulation
Note
We are strongly recommending first performing the tasks in the live environment.

Live Environment

In this exercise, you will perform the following steps:

  1. Build a user interface with SAP Fiori elements1.
  2. Modify the user interface with OData annotations.
  3. Check the annotation files.

Prerequisite

Please make sure that by this moment you have successfully implemented an SAP CAP-based service.

Steps

  1. Generate the UI with an SAP Fiori Elements Template.

    1. In SAP Business Application Studio, invoke the Command Palette (ViewFind Command or Cmd+Shift+P) and choose Fiori: Open Application Generator.

    2. Choose SAP Fiori Elements and List Report Object Page and select Next.

    3. In the next dialog, choose Use a Local CAP Project and point to the folder of your current RiskManagement project. Select RiskService (Node.js) as the OData service and select Next.

    4. As the Main entity choose Risks as answer to the question choose No.

    5. Enter risks as the module name. Enter Risks as the application title and Risk Management as the description for the application. Enter riskmanagement as the namespace. Choose No for all additional settings. Choose Finish.

      (If you get a pop-up that says A project has been generated. What would you like to do with it?, you can ignore it and just close the pop-up).

      The application is now generated and after a couple of seconds you can see it in the app folder of your project. It contains a risks and a webapp folder with a Component.js file, which is characteristic for a UI5 app. However, the code there is minimal and it basically inherits its logic from the sap/fe/core/AppComponent.

    6. If cds watch isn't still running from the previous lesson, execute it in a terminal and press on the Open in New Tab button in the right lower corner. If it is still running from the last exercise, it is enough to refresh the browser page where it is running.

      You can now see that cds watch has discovered an HTML page in your app folder:

    7. Click on this link. On the launch page that now comes up, Choose the Risks tile.

      You can now see the list page, it looks like this:

      Unfortunately, the app looks rather empty, for example, the list has no columns yet. This is because we miss an essential part of a SAP Fiori elements application that tells it about columns, form fields and many other things: It is missing UI annotations.

  2. Modify the UI with OData annotations.

    Now we are going to modify the UI with annotations.

    Since, our entire UI content goes into the app/ folder, we create our annotation files inside this folder.

    Project Folder/fileContent
    app/UI content
    db/Domain Models and db-related content
    srv/Service definitions and implementations
    package.jsonYour project descriptor

    The SAP Fiori Generator automatically generates the services.cds file inside the app folder. This file ensures all annotation files are loaded: using from'./risks/annotations';

    In case you are splitting up your annotations into multiple files, make sure that you also include the files in the services.cds.

    Usually, you can also have multiple SAP Fiori / front end projects in your CAP project. To avoid writing redundant annotations for the same entities or schemas, you can create - based on the guidelines - the file common.cds inside the app/ folder. All annotations inside this file will then apply to all UI5-Applications.

    1. To add the OData annotations, in the project, go to folder app representing the service and select New File in the context menu.

    2. Enter common.cds as a name.

    3. Click on the new file in the explorer.

      An editor opens.

    4. Enter the following lines into the editor:

      Code snippet
      using riskmanagement as rm from '../db/schema';
      
       // Annotate Risk elements
       annotate rm.Risks with {
       ID     @title : 'Risk';
       title  @title : 'Title';
       owner  @title : 'Owner';
       prio   @title : 'Priority';
       descr  @title : 'Description';
       miti   @title : 'Mitigation';
       impact @title : 'Impact';
       } 
      
      // Annotate Miti elements
       annotate rm.Mitigations with {
       ID @( 
            UI.Hidden,
            Common : {Text : descr}
       ); 
      owner @title : 'Owner';
      descr @title : 'Description';
       }
      
      annotate rm.Risks with {
         miti @(Common : {
          //show text, not id for mitigation in the context of risks
          Text            : miti.descr,
          TextArrangement : #TextOnly,
          ValueList       : {
          Label          : 'Mitigations',
          CollectionPath : 'Mitigations',
          Parameters     : [
             {
             $Type : 'Common.ValueListParameterInOut',
             LocalDataProperty : miti_ID,
             ValueListProperty : 'ID'
             },
             {
             $Type : 'Common.ValueListParameterDisplayOnly',
             ValueListProperty : 'descr'
             }
          ]
          }
        });
       }
      Copy code
    5. Now we have to include the common.cds file into the services.cds file:

      Code snippet
      using from './risks/annotations';
       using from './common';
      Copy code
    6. Open app/risks/annotations.cds. Here we are going to use UI Annotations to tell SAP Fiori Elements how the List and Object page should look. These annotations will only apply to the risks app.

      Code snippet
      using RiskService from '../../srv/risk-service';
       // Risk List Report Page
       annotate RiskService.Risks with @(UI : {
          HeaderInfo : {
             TypeName : 'Risk',
             TypeNamePlural : 'Risks',
             Title : {
                $Type : 'UI.DataField',
                Value : title
             },
             Description : {
                $Type : 'UI.DataField',
                  Value : descr
             }
          },
          SelectionFields : [prio],
          Identification : [{Value : title}],
          // Define the table columns
          LineItem : [
             {Value : title},
             {Value : miti_ID},
             {Value : owner},
             { 
                Value : prio,
                Criticality : criticality
             },
             {
                Value : impact,
                Criticality : criticality
             },
          ],
       });
       // Risk Object Page
       annotate RiskService.Risks with @(UI : {
           Facets : [{
              $Type : 'UI.ReferenceFacet',
              Label : 'Main',
              Target : '@UI.FieldGroup#Main',
           }],
           FieldGroup #Main : {Data : [
             {Value : miti_ID},
             {Value : owner},
             {
                 Value : prio,
                 Criticality : criticality
             },
             { 
                 Value : impact,
                 Criticality : criticality
             }
          ]},
       });
      Copy code
    7. Save all files.

      As in the steps before, cds watch has noticed the new file and compiled the service again, so now it contains the additional annotations.

    8. In the browser, reload the test page, which shows the service and the index page. Select the index page link /risks/webapp/index.html. On the launch page that now comes up, choose the Risks tile. Select Go. It now shows a work list with some columns and the data from the service.

      You’ve now already developed a full-blown service with a full-blown UI application on top, running locally.

  3. Check the Annotation Files.

    1. Let's have a look at the common.cds file and the annotations in there.

      At the beginning you see:

      Code snippet
      using riskmanagement as rm from '../db/schema';
      
       // Annotate Risk elements
       annotate rm.Risks with {
          ID @title : 'Risk';
          title @title : 'Title';
          owner @title : 'Owner';
          prio @title : 'Priority';
          descr @title : 'Description';
          miti @title : 'Mitigation';
          impact @title : 'Impact';
       }
      Copy code

      It's referring to the definitions of the schema.cds file that defines the Risks and Mitigations entities. Then it annotates the Risk entity with numerous texts. These should be in a translatable file normally, but for now, we will keep them here. These texts are used as labels in form fields and column headers by SAP Fiori elements.

    2. Next, take a look at the app/risks/annotations.cds file:

      Code snippet
      using RiskService from '../../srv/risk-service';
      
       // Risk List Report Page
       annotate RiskService.Risks with @(UI : {
          HeaderInfo : {
             TypeName : 'Risk',
             TypeNamePlural : 'Risks',
             Title : {
                $Type : 'UI.DataField',
                Value : title 
      }, 
      Description : {
       $Type : 'UI.DataField',
       Value : descr
       }
       },
       SelectionFields : [prio],
       Identification : [{Value : title}],
       // Define the table columns
           LineItem : [
              {Value : title},
              {Value : miti_ID},
              {Value : owner},
              { 
                  Value : prio,
                  Criticality : criticality 
              },
              { 
                  Value : impact,
                  Criticality : criticality
              },
          ],
       });
      Copy code

      This file defines the content of the work list page and the object page, to which you are navigated, when you select a line in the work list.

      The SelectionFields section defines which of the properties are exposed as search fields in the header bar above the list, in this case prio is the only explicit search field.

      From the LineItem section all the columns and their order of the work list are derived. While in most cases the columns are defined by Value: followed by the property name of the entity, in the case of prio and impact there’s also Criticality, which for now you can disregard, but keep it in mind in case you go to the later modules. It currently adds a diamond icon right left of the fields. You can just ignore it.

    3. The next section defines the content of the object page:

      Code snippet
      // Risk Object Page
       annotate RiskService.Risks with @(UI : {
          Facets : [{ 
             $Type : 'UI.ReferenceFacet',
             Label : 'Main',
             Target : '@UI.FieldGroup#Main',
          }],
          FieldGroup #Main : {Data : [
            {Value : miti_ID},
            {Value : owner},
            {
                Value : prio, 
                Criticality : criticality 
            },
            { 
                Value : impact,
                Criticality : criticality
            } 
         ]},
       });
      Copy code

      This section defines a single facet, a ReferenceFacet, of the field group FieldGroup#Main. This field group just shows up as a form. The properties of the Data array within FieldGroup#Main determine the fields in the form:

    4. The last part of the common.cds file is the most complicated one:

      Code snippet
      annotate rm.Risks with {
          miti @(Common : {
          //show text, not id for mitigation in the context of risks
          Text : miti.descr,
          TextArrangement : #TextOnly, 
          ValueList : {
             Label : 'Mitigations',
             CollectionPath : 'Mitigations',
             Parameters : [
               { 
                  $Type : 'Common.ValueListParameterInOut',
                  LocalDataProperty : miti_ID,
                  ValueListProperty : 'ID'
               },
               {
                  $Type : 'Common.ValueListParameterDisplayOnly',
                  ValueListProperty : 'descr'
               }
            ]
          }
        }); 
      }
      Copy code

      Without these lines, you would see the id of the mitigations from the miti field, in both the list and the object page:

      By introducing the annotations for the miti property, instead of just displaying the original value of miti, that is, the ID, the UI shows its description property. The subsequent part ValueList introduces a value help for miti that you can see on the object page in its edit mode. The value help takes the id as an input parameter and again displays the description parameter.

    Platform Simulation

    Click on the Start button below to open a simulation of the platform. Then follow the step-by-step instructions to generate a UI using SAP Fiori Elements.

Result

Well done! You have created a SAP Fiori Elements UI for your application. In the next unit you will add custom business logic to your application to add highlighting to some fields.

Reference Links: Generating a User Interface

For your convenience, this section contains the external references in this lesson.

If links are used multiple times within the text, only the first location is mentioned in the reference table.

Ref#SectionContext text fragmentBrief descriptionLink
1Task FlowBuild a user interface with SAP Fiori elementsSAP Fiori elementshttps://experience.sap.com/fiori-design-web/smart-templates/

Save progress to your learning plan by logging in or creating an account