Create an SAP Fiori Elements-Based UI
- How to create an SAP Fiori elements app on top of your previously created CAP application
- How to modify the UI with OData annotations
- How to make header info editable
- How to check the annotation files
Prerequisites
- Before you start with this tutorial, you have two options:
- Follow the instructions in Step 16: Start from an example branch of Prepare Your Development Environment for CAP to checkout the
create-cap-application
branch. - Complete the previous tutorial Create a CAP-Based Application with all its prerequisites.
- Follow the instructions in Step 16: Start from an example branch of Prepare Your Development Environment for CAP to checkout the
- Step 1
An SAP Fiori elements app is an application that leverages SAPUI5, SAPUI5 controls, and SAPUI5 model view controller (MVC) concepts. In a plain SAPUI5 or a freestyle SAPUI5 app, all the views and controllers are part of your project. In contrast, in an SAP Fiori elements app most of the code is outside of the project, managed centrally by the SAP Fiori elements team. The code inside your project only references these central components. They take care of creating the UI according to the latest SAP Fiori design guidelines and cover 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.
- Step 2
-
In VS Code, invoke the Command Palette ( View → Command Palette or Shift + Command + P for macOS / Ctrl + Shift + P for Windows) and choose Fiori: Open Application Generator.
VS Code will automatically install
@sap/generator-fiori
if missing and open the Template Wizard.In case you get an error launching the Application Generator, refer to the FAQ to find a solution.
-
Choose application type SAP Fiori elements and floor plan List Report Object Page.
-
Choose Next.
-
In the next dialog, choose Use a Local CAP Project and point to the folder of your current
cpapp
project.In case you get the error:
Node module @sap/cds isn't found. Please install it and try again.
This is an issue with the App Generator not finding the corresponding CAP modules, due to different repositories. This should be a temporary issue. For the meantime you can work around it by opening a command line and running the following command:
bashCopynpm install --global @sap/cds-dk --@sap:registry=https://npmjs.org/
See the CAP Troubleshooting guide for more details.
-
Select the
RiskService(Node.js)
as the OData service and choose Next. -
Select Risks as the main entity, choose the option No to avoid adding table columns automatically. Choose Next.
-
Enter
risks
as the module name andRisks
as the application title. -
Enter
ns
as the namespace andRisks
as the description for the application. -
Choose Finish to generate the application.
The application is now generated and in a few seconds you can see it in the
app
folder of your project. It contains arisks
and awebapp
folder with aComponent.js
file that is characteristic for an SAPUI5 app.However, the code there’s minimal and it basically inherits its logic from the
sap/fe/core/AppComponent
. Thesap/fe/core/AppComponent
is the base class for SAP Fiori elements. This class is managed centrally by SAP Fiori elements, so you don’t need to modify it yourself.In which folder can you see your application?
-
- Step 3
-
If it’s not still running from the previous tutorial, execute
cds watch
in a VS Code terminal and switch to http://localhost:4004 in your browser.You can now see that the CAP server has discovered an HTML page in your
app
folder: -
Choose the link http://localhost:4004/risks/webapp/index.html for the HTML page.
-
You can now see the application without any data.
The table is empty because the application is currently missing UI annotations. You add them in the next step.
-
To add the OData annotations, copy the file
risks-service-ui.cds
fromtemplates/create-ui-fiori-elements/srv
to thesrv
folder of your app.As in the steps before, the CAP server has noticed the new file and compiled the service again, so now it contains the additional annotations.
-
In your browser, reload the page of the empty SAP Fiori elements app.
-
Choose Go.
It now shows a work list with some columns and the data from the service.
If the work list doesn’t show, you might have to clear your cache.
You’ve now already finished a full blown service and a UI application on top running locally.
-
- Step 4
Let’s say that at this point you’d like to edit some of the data or create a new risk in the table. By default, the header info is not editable. Hence, you’ll be able to fill in data in the main group fields
Mitigation
,Priority
, andImpact
, but won’t be able to fill data in any of the header fieldsTitle
orDescription
. Let’s try it out.Choose Create.
To add a
Mitigation
, click on the value help icon in the input field, select a mitigation, and choose OK.Try and fill in data in the main group fields
Priority
andImpact
and choose Create.The new risk is created but it has no title and it has no description.
To make also the header fields editable, you have to change the default setting for this in the
manifest.json
file on theRisks
application.Open
app/risks/webapp/manifest.json
file.Change the value of the setting
editableHeaderContent
totrue
:YAMLCopy{ "_version": "1.32.0", "sap.app": { ... "sap.ui5": { ... "routing": { ... "targets": { ... "RisksObjectPage": { ... "options": { "settings": { "editableHeaderContent": true, "entitySet": "Risks" } } } } }, ... }
Create another risk with a title and description.
- Step 5
Let’s have a look at the new
risk-service-ui.cds
file and the annotations in there. At the beginning you see:JavaScriptCopyusing RiskService from './risk-service'; annotate RiskService.Risks with { title @title: 'Title'; prio @title: 'Priority'; descr @title: 'Description'; miti @title: 'Mitigation'; impact @title: 'Impact'; }
It’s referring to the definitions of the earlier
cds
file that exposes the service and itsRisks
andMitigations
entities. Then it annotates theRisks
entity with a number of texts. These should be in a translatable file normally but for now we keep them here. These texts are used as labels in form fields and column headers by SAP Fiori elements.The following section is needed for the value help of the Mitigation field that is visible when you are editing the object page of the
Risks
app.JavaScriptCopyannotate RiskService.Mitigations with { ID @( UI.Hidden, Common: { Text: description } ); description @title: 'Description'; owner @title: 'Owner'; timeline @title: 'Timeline'; risks @title: 'Risks'; }
Next up:
JavaScriptCopyannotate RiskService.Risks with @( UI: { HeaderInfo: { TypeName: 'Risk', TypeNamePlural: 'Risks', Title : { $Type : 'UI.DataField', Value : title }, Description : { $Type: 'UI.DataField', Value: descr } }, SelectionFields: [prio], LineItem: [ {Value: title}, { Value: miti_ID, ![@HTML5.CssDefaults] : {width : '100%'} }, { Value: prio, Criticality: criticality }, { Value: impact, Criticality: criticality } ], Facets: [ {$Type: 'UI.ReferenceFacet', Label: 'Main', Target: '@UI.FieldGroup#Main'} ], FieldGroup#Main: { Data: [ {Value: miti_ID}, { Value: prio, Criticality: criticality }, { Value: impact, Criticality: criticality } ] } }, ) { };
This defines the content of the work list page and the object page that you navigate to when you click on a line in the work list.
The
HeaderInfo
describes the key information of the object, which will make the object page to displaytitle
of the risk as title and thedescr
as subtitle in its header area.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.The columns and their order in the work list are derived from the
LineItem
section. While in most cases the columns are defined byValue:
followed by the property name of the entity, in the case ofprio
andimpact
there’s alsoCriticality
. For now, you can neglect it but keep it in mind in case you go to the later modules.Next up is the
Facets
section. In this case, it defines the content of the object page. It contains only a single facet, aReferenceFacet
, of the field groupFieldGroup#Main
. This field group just shows up as a form. The properties of theData
array withinFieldGroup#Main
determine the fields in the form.At the end of the file you see:
JavaScriptCopyannotate RiskService.Risks with { miti @( Common: { //show text, not id for mitigation in the context of risks Text: miti.description , TextArrangement: #TextOnly, ValueList: { Label: 'Mitigations', CollectionPath: 'Mitigations', Parameters: [ { $Type: 'Common.ValueListParameterInOut', LocalDataProperty: miti_ID, ValueListProperty: 'ID' }, { $Type: 'Common.ValueListParameterDisplayOnly', ValueListProperty: 'description' } ] } } ); }
The line
Text: miti.description , TextArrangement: #TextOnly,
declares that the text from the description property is displayed for themiti
association. Then it adds a value help (ValueList
) for that association, so the user can pick one of the available mitigations when editing the object page.The result of this tutorial can be found in the
create-ui-fiori-elements
branch.