Generating a User interface

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

   1. In SAP Business Application Studio, invoke the Command Palette (View → Find 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.

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.

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. Modify the UI with OData annotations.

   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

      Copy code

      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

      Copy code

      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 Listand Object page should look. These annotations will only apply to the risks app.

      Code snippet

      Copy code

      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.

      

Let's have a look at the common.cds file and the annotations in there. At the beginning, we see:

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';
 }

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.

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

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
        },
    ],
 });

Note

You will find the code block without page break a few pages later.

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.

The next section defines the content of the object page:

// 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
      } 
   ]},
 });

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:

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

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'
         }
      ]
    }
  }); 
}

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.

1. Check the files.

   1. Check the files as described above.