Generating a User interface

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.

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 List and 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.

   

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

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

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

   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

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

   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

   Copy code

   // 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

   Copy code

   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.

ExerciseStart Exercise