第 162 页 / 共 465 页
4 Developing an SAP Fiori Elements List Report and Object Page
4.4.2 Activating the OData Service on the SAP Gateway Hub System
To activate the OData service in the SAP Gateway system and to map the technical
OData service name to the corresponding backend service, we have to carry out the
following steps:
1. Open an embedded SAP GUI session in Eclipse for the SAP Gateway hub system by
selecting the ABAP system in the Project Explorer in Eclipse and using the shortcut
(Ctrl)+(6) or by using the SAP GUI launcher in the toolbar.
2. This opens an embedded SAP GUI in Eclipse and provides the full functionality of
the classic ABAP workbench. To run Transaction /IWFND/MAINT_SERVICE (Main-
tain Service), enter the transaction code into the command field in the upper-left
corner or run it as an ABAP development object by using the shortcut (Alt)+(F8).
3. To add a new service to the Service Catalog, click the Add Service button in the tool-
bar (Figure 4.25).
Figure 4.25 Adding a New OData Service to the Service Catalog of the SAP Gateway Hub
System
4. On the Add Selected Services screen, enter the system alias of your backend ABAP
system and the Technical Service Name. In our case, we entered “Z_C_Purchase-
DocumentLRP_CDS”.
5. Click the Get Services button to request the available service from the backend
(Figure 4.26).
Figure 4.26 Found Backend Service to Be Added to the Service Catalog
162
第 163 页 / 共 465 页
4.4 Creating an OData Service
6. Select the table line of the service, and click the Add Selected Services button in the
toolbar.
7. Don’t change the default values, and only assign a productive non-$tmp package if
you want to transport the service activation (Figure 4.27).
Figure 4.27 Add Service Dialog
8. Confirm all dialogs. The service is added to the Service Catalog of the SAP Gateway
hub system and has the status Active (Figure 4.28).
Figure 4.28 The Newly Activated Service in the Service Catalog of the SAP Gateway
Hub System
163
第 164 页 / 共 465 页
4 Developing an SAP Fiori Elements List Report and Object Page
4.4.3 Testing the OData Service Using the SAP Gateway Client
The newly generated and activated OData service can easily be tested from the Ser-
vice Catalog in the SAP Gateway hub system by selecting the service and opening the
Sap Gateway Client from the toolbar of the ICF nodes pane (see Figure 4.29). The SAP
Gateway client is an HTTP client that allows you to easily test your OData service
using the embedded SAP GUI window in Eclipse. You can also directly open the SAP
Gateway Client using Transaction /IWFND/GW_CLIENT.
To test an OData service endpoint, follow these steps:
1. Select the HTTP method you would like to use from the HTTP Method radio button
group, for instance, GET for reading OData entities or metadata (Figure 4.29).
Figure 4.29 The SAP Gateway Client on the SAP Gateway Hub System
2. Enter the requested URI you want to test in the Request URI input field. You can
freely modify the URI in the input field or select one of the predefined URI options
using the Add URI Option button in the SAP Gateway Client toolbar (e.g., $metadata
for displaying the service metadata document).
3. In the HTTP Request screen area, you can set the HTTP header fields and the pay-
load of the request either manually or by uploading a file.
4. Choose Execute in the toolbar to send the HTTP request or simply press (F8). The
HTTP response will be displayed in the HTTP Response area.
4.5 Adding User Interface Annotations
The UI of our application will be based on the SAP Fiori elements list report and object
page templates. In contrast to SAP Fiori freestyle applications, the layout of SAP Fiori
164
第 165 页 / 共 465 页
4.5 Adding User Interface Annotations
elements apps is relatively fixed, and UI controls can’t be placed at will on the page.
However, when using SAP Fiori elements template-based apps, we must specify
which field will be displayed at which predefined position of the template using CDS
@UI annotations. In the following subsections, we’ll follow the steps to specify the UI
annotations required for our purchasing application. Additionally, we’ll also intro-
duce non-UI annotations that will also influence the layout and functionality of the
UI, for instance, @Search annotations.
4.5.1 Creating a Metadata Extension File
You can either add UI annotations directly into the CDS DDL file or create a metadata
extension file. If you create a lot of UI annotations, which is normally the case when
using SAP Fiori elements template-based apps, it might make sense to move those
annotations to a separate file to avoid cluttering the core CDS view with loads of UI
annotations. You can create a metadata extension file by proceeding as follows:
1. Open the ABAP perspective in the ABAP development tools in Eclipse.
2. In the ABAP project, select the package node in which you want to create the table
via the Project Explorer view.
3. Right-click on the package and select New (cid:2) Other ABAP Repository (cid:2) Core Data Ser-
vices (cid:2) Metadata Extension.
4. The metadata extension creation wizard appears where you can enter a Name and
Description. We’ll call the purchase documents metadata extension Z_C_Purchase-
DocumentLrp and the purchase document items metadata extension Z_C_Purchase-
DocumentItemLrp. By convention, metadata extension files will have the same
name as the annotated DDL sources.
5. Click Finish, and the source code editor will open.
In the metadata extension file, you must define which CDS view you want to anno-
tate. In our case, we first want to annotate the purchase document view Z_C_Pur-
chaseDocumentLRP to configure the list report. Additionally, you must specify the
priority of the metadata extension by assigning it to a layer. The #CORE layer has the
lowest priority, whereas the #CUSTOMER layer has the highest priority. We’ll simply
go with the #CORE layer to make it possible to overwrite our UI annotations at a later
point in time without having to change the core extension file (Listing 4.22).
165
第 166 页 / 共 465 页
4 Developing an SAP Fiori Elements List Report and Object Page
@Metadata.layer: #CORE
annotate view Z_C_PurchaseDocumentLRP with{…}
Listing 4.22 Metadata Extension File Header for the Z_C_PurchaseDocumentLRP CDS View
To enable metadata extensions from the CDS DDL side, the following annotation
must be added on the header level: @Metadata.allowExtensions:true. All UI annota-
tions we’ll introduce in the following sections will be added to the metadata exten-
sions we just created for the purchase document and purchase document item CDS
consumption views (Z_C_PurchaseDocumentLrp and Z_C_PurchaseDocumentItemLrp).
4.5.2 User Interface-Relevant Annotations for the List Report
In this section, we’ll go through the most important UI annotations of the list report
template and configure the UI of our purchase document list report. In Figure 4.30,
you can see an overview of the most important list report CDS UI annotations and
how they are reflected on the UI. To configure the UI of the list report, we must anno-
tate the Z_C_PurchaseDocumentItemLrp CDS view because the corresponding purchase
document OData entity will be bound to the list report screen.
@UI.selectionField
@Search.searchable: true
@UI.headerInfo @UI.lineItem
Figure 4.30 Most Important List Report CDS UI Annotations and How They Will Be Reflected
in the List Report Template
Line Item Annotation
To specify which fields of the Z_C_PurchaseDocumentLRP OData entity will initially be
displayed as columns in the table of the list report, we must annotate these fields
with the @UI.lineItem annotation. How this looks for the PurchaseDocument field,
which we want to display as the second column in the table, is shown in Listing 4.23.
166
| @Search.searchable: true | |
|---|---|
| @UI.headerInfo | |
|---|---|
第 167 页 / 共 465 页
4.5 Adding User Interface Annotations
@UI.lineItem: [{ importance: #HIGH, position: 20 }]
PurchaseDocument;
Listing 4.23 Line Item Annotation for the PurchaseDocument Field
We must specify the position of the field by which the columns of the table are
sorted. Additionally, we can also define the importance of the field. Fields annotated
with importance: #HIGH will always be displayed, for instance, also when the table is
rendered on small displays. If no importance is specified, the line item is treated as
having importance #LOW.
Header Info Annotation
The header of the table can be set using the header-level UI annotation @UI.header-
Info. For the list report, the value specified for typeNamePlural will be used as the title
of the table (Listing 4.24).
@UI.headerInfo: {
…
typeNamePlural: 'Purchase Documents',
… }
Listing 4.24 Header Info typeNamePlural Annotation for Purchase Documents
Image Annotation
The @UI.headerInfo annotation also contains an imageUrl annotation to define a field
containing URLs for images to display in the application. In our case, we’ll reference
the PurchaseDocumentImageURL field (Listing 4.25).
@UI.headerInfo: {
…
imageUrl: 'PurchaseDocumentImageURL'
… }
Listing 4.25 Header Info imageUrl Annotation for Purchase Documents
Additionally, the PurchaseDocumentImageURL field must also be annotated with
@Semantics.imageUrl: true. If we then add the field as the first column in our table
using the @UI.lineItem annotation introduced previously, the template will automat-
ically render an HTML <img> tag with the src property set to the image URL provided
by the field value.
167
第 168 页 / 共 465 页
4 Developing an SAP Fiori Elements List Report and Object Page
Criticality Annotation
We’ll use the OverallPriceCriticality field value calculated in the backend CDS
layer to indicate the criticality of the OverallPrice column (Listing 4.26). Depending
on the overall price criticality value, the overall price field value will be displayed in a
certain color (Table 4.3). The criticality annotation is also part of the @UI.lineItem
annotation.
@UI.lineItem: [{ importance: #HIGH, position: 40, criticality:
'OverallPriceCriticality', value: 'OverallPrice' }]}
OverallPrice;
Listing 4.26 Line Item Criticality Annotation for the OverallPrice Field
Criticality Value Color
3 – Not critical Green
2 – Medium criticality Yellow
1 – High criticality Red
0 – Undefined No color
Table 4.3 Mappings between Criticality Value and Color
We also use the OverallPriceCriticality field value in the same way to indicate the
criticality of the IsApprovalRequired field.
Contact Quick View
It’s also possible to display a contact information quick view for a field by adding the
type: #AS_CONTACT annotation (Listing 4.27), which is also part of the @UI.lineItem
annotation (Figure 4.31).
The data of the quick view has to be provided via an association value: '_Purchasing-
Organization' where the associated view must contain several semantically anno-
tated fields (Listing 4.28).
@UI.lineItem: [{ importance: #MEDIUM, position: 60, type: #AS_
CONTACT, value: '_PurchasingOrganization', label: 'Purchasing Organization' }]
PurchasingOrganization;
Listing 4.27 Contact Quick View Annotation for the PurchasingOrganization Field
168
| Criticality Value | Color |
|---|---|
| 3 – Not critical | Green |
| 2 – Medium criticality | Yellow |
| 1 – High criticality | Red |
| 0 – Undefined | No color |
第 169 页 / 共 465 页
4.5 Adding User Interface Annotations
…
@Semantics.text: true
@Semantics.name.fullName: true
description as Description,
@Semantics: {
eMail.address: true,
eMail.type: [ #WORK ]
}
emailaddress as Email,
@Semantics.telephone.type: [ #WORK ]
phonenumber as Phone,
@Semantics.telephone.type: [ #FAX ]
faxnumber as Fax
…
Listing 4.28 Required Annotations for the Contact Quick View in the Associated View
Figure 4.31 Contact Quick View for the Purchasing Organization
Selection Field Annotation
To make certain fields appear in the expanded filter bar area of the list report as selec-
tion fields, we must annotate those fields with the @UI.selectionField annotation. As
with the line item annotation, we also must specify the position annotation to sort
the selection fields. In Listing 4.29, you can see how the PurchaseDocument and Prior-
ity fields must be annotated to appear in sequence.
169
第 170 页 / 共 465 页
4 Developing an SAP Fiori Elements List Report and Object Page
…
@UI.selectionField: [{ position: 10 }]
PurchaseDocument;
@UI.selectionField: [{ position: 20 }]
Priority;
…
Listing 4.29 Selection Field Annotation for the Filter Bar
The other selection fields displayed previously in Figure 4.30 must be annotated
accordingly with increasing position values.
Searchable Annotation
The @Search.searchable: true header level annotation marks a CDS view entity
relevant for search scenarios. Additionally, by annotating certain fields with
@Search.defaultSearchElement: true, those elements will be considered in freestyle
searches and form the search scope. In our case, we’ll annotate the purchase docu-
ment Description field with search annotations in the main CDS view. We’ll do this
directly in the main view, not in the metadata extension, as we only want to move UI
annotations to the metadata extension file. We’ll also introduce an @Search.fuzzi-
nessThreshold to make our search somewhat error tolerant. The value can vary
between 0 and 1, where 1 means that only exact matches will be returned by the
search. We’ll use the recommended value 0.7, which introduces some fuzziness but
not too much:
…
@Search.defaultSearchElement : true
@Search.fuzzinessThreshold : 0.7
@Semantics.text: true
Description,
…
@Search annotations don’t belong to the UI annotation category but annotating the
purchase document CDS view entity with @Search annotations will lead to the render-
ing of a freestyle search field in the list report template, as shown earlier in Figure
4.30. When generating an OData service metadata document, SADL will consider
search annotations and set the EntitySet property sap:searchable to true, indicating
to the UI or consuming clients that the entity supports freestyle search. When send-
ing a search query for a certain entity, SADL will trigger a SAP HANA text search
170
第 171 页 / 共 465 页
4.5 Adding User Interface Annotations
(transparent to the developer) considering the fuzziness indicator and the search
scope formed by the @Search.defaultSearchElement: true annotated fields of the CDS
view.
The OData search request GET Z_C_PurchaseDocumentLrp?search=<SEARCH_TERM>&… will
be transformed by SADL to a SAP HANA fuzzy text search SELECT statement making
use of the SAP HANA CONTAINS predicate:
SELECT … FROM Z_C_PurchaseDocumentLRP WHERE CONTAINS(Description, <SEARCH_
TERM>, FUZZY(0.7))…;
Value Helps
By default, the value help support of selection fields is based on foreign key associa-
tions. If a field is annotated with @ObjectModel.foreignKey.association: <_ASSOCIA-
TION>, and its foreign key association is also exposed in the CDS view, then SADL will
take this information into account when generating the OData service and create value
help annotations for the key field of the associated view. You can find those annota-
tions in the service metadata document. The generated status value help OData anno-
tations are shown in Figure 4.32. The CDS view that the value help is based on is the
associated status view Z_I_PurchaseDocumentStatus. The Status field is an in and out
parameter, whereas the StatusText is only a display parameter of the value help.
Figure 4.32 Generated Value Help Annotation for the Status Field
Enabling Quick Actions
The quick actions we’ve added to the BOPF purchase document root node can be
enabled on the list report UI by adding the @UI.lineItem annotations shown in Listing
4.30 to the PurchaseDocument field.
171
第 172 页 / 共 465 页
4 Developing an SAP Fiori Elements List Report and Object Page
@UI: {
lineItem: [
…
{ type: #FOR_ACTION, dataAction: 'BOPF:APPROVE', label: 'Approve', position: 1 },
{ type: #FOR_ACTION, dataAction: 'BOPF:CLOSE', label: 'Close', position: 2 }],
…
]
}
PurchaseDocument;
Listing 4.30 Line Item Annotation to Enable BOPF Quick Actions on the List Report UI
4.5.3 User Interface Annotations for the Object Page
To configure the object page shown later in Figure 4.34, we must mainly annotate the
Z_C_PurchaseDocumentLRP CDS view as the data we want to display in the header in the
Purchase Document section provided by this CDS view. The Z_C_PurchaseDocument-
ItemLRP must be annotated with @UI.lineItem annotations to configure the items
table contained in the Purchase Document Items section of the object page.
Header Info Annotation
The object page title and subtitle can be configured using the @UI.headerInfo.title
and description annotations (Figure 4.33). In our case, we want to display the Descrip-
tion and PurchaseDocument fields of the Z_C_PurchaseDocumentLRP entity in these posi-
tions of the template layout (Listing 4.31).
@UI: {
headerInfo: {
description: {
value: 'Description',
type: #STANDARD
},
title: {
value: 'PurchaseDocument',
type: #STANDARD
},
…
}
}
Listing 4.31 Header Info Description and Title Annotation
172
第 173 页 / 共 465 页
4.5 Adding User Interface Annotations
@UI.headerInfo
@UI.facet (purpose: #HEADER, type: #DATAPOINT_REFERENCE)
Figure 4.33 CDS UI Annotations for the Object Page Header
Data Point Header Facet Annotation
Furthermore, we want to add several data points to the header section of the object
page to highlight several values: Status, OverallPrice, IsApprovalRequired, and Prior-
ity (refer to Figure 4.33). Therefore, we must create several header facets using the
@UI.facet annotation with purpose: #HEADER and type: #DATAPOINT_REFERENCE. Via the
targetQualifier annotation, the facets reference corresponding fields annotated with
the @UI.dataPoint annotation. As an example, Listing 4.32 shows the required anno-
tations for displaying the OverallPrice field as a data point header facet.
@UI.facet: [
…
{
id: 'OverallPriceDataPointFacet',
purpose: #HEADER,
type: #DATAPOINT_REFERENCE,
targetQualifier: 'OverallPrice'
},
…
]
}
PurchaseDocument;
…
@UI.dataPoint: { title: 'Overall Price', criticality: 'OverallPriceCriticality
' }
OverallPrice;
…
Listing 4.32 Data Point Header Facet Annotations for the OverallPrice Field
173
第 174 页 / 共 465 页
4 Developing an SAP Fiori Elements List Report and Object Page
Facet Annotation
The different sections of an object page are defined using @UI.facet annotations (Fig-
ure 4.34). The Purchase Document section is defined as a collection facet using the
@UI.facet.type: #COLLECTION annotation. The section includes two field groups, Basic
Data and Purchasing Data, which are defined using reference facets (@UI.facet.type:
#FIELDGROUP_REFERENCE), and in turn reference field groups are defined with the
@UI.fieldGroup annotation. To group reference facets into the same collection facet,
reference facets must provide the @UI.facet.parentId annotation pointing to the ID
annotation of the collection facet. Fields with the same field group qualifier annota-
tion, in our case, PurchasingDocumentFieldGroup or BasicDataFieldGroup, are assigned
to the same field groups. The Purchase Document Items section is defined using the
@UI.facet.type: #LINEITEM_REFERENCE annotation and references the _PurchaseDocu-
mentItem association.
@UI.facet (type: #COLLECTION)
@UI.facet (type: #LINEITEM_REFERENCE)
@UI.fieldGroup
@UI.fieldGroup
@UI.facet (type:#FIELDGROUP_
REFERENCE)
@UI.facet (type:#FIELDGROUP_REFERENCE)
@UI.lineItem
Figure 4.34 Sections of an Object Page and Their Corresponding UI Annotations
174
| @UI.facet (type: #COLLECTION) | |
|---|---|
| R | @UI.facet (type:#FIELDGROUP_ EFERENCE) |
| @UI.facet (type: #LINEITEM_REFERENCE) |
|---|
| @UI.fieldGr | |
|---|---|
| @UI.facet (type:#FIELDGROUP_REFERE | NCE) |
第 175 页 / 共 465 页
4.5 Adding User Interface Annotations
The columns of the items table are defined using @UI.lineItem annotations. In Listing
4.33, you can find an excerpt of the required annotations for defining the UI shown in
Figure 4.34.
@UI: {
facet:[
...
// Purchase Document Section
{
label: 'Purchase Document',
type: #COLLECTION,
id: 'PurchaseDocumentCollectionFacet',
purpose: #STANDARD
},
// Basic Data field group
{
label: 'Basic Data',
type: #FIELDGROUP_REFERENCE,
id: 'BasicDataFieldGroupReferenceFacet',
parentId: 'PurchaseDocumentCollectionFacet',
purpose: #STANDARD,
targetQualifier: 'BasicDataFieldGroup'
},
// Purchasing Data field group
{
label: 'Purchasing Data',
type: #FIELDGROUP_REFERENCE,
id: 'PurchasingDocumentFieldGroupReferenceFacet',
parentId: 'PurchaseDocumentCollectionFacet',
purpose: #STANDARD,
targetQualifier: 'PurchasingDocumentFieldGroup'
},
// Items Section
{
label: 'Purchase Document Items',
type: #LINEITEM_REFERENCE,
id: 'PurchaseDocumentItemsLineItemReferenceFacet',
purpose: #STANDARD,
targetElement: '_PurchaseDocumentItem'
}
],
fieldGroup: [{ qualifier: 'PurchasingDocumentFieldGroup',
position: 10, importance: #HIGH }]
175
第 176 页 / 共 465 页
4 Developing an SAP Fiori Elements List Report and Object Page
}
PurchaseDocument;
...
@UI.fieldGroup: [{ qualifier: 'BasicDataFieldGroup', position: 10, importance: #HIGH }]
crea_date_time;
…
Listing 4.33 Excerpt of the Required CDS UI Annotations for Defining Object Page Sections
and Field Groups
Line Item Annotation
The columns of the purchase document items table on the object page are defined via
@UI.lineItem annotations. In this case, the annotations must be added to the meta-
data extension file of the Z_C_PurchaseDocumentItemLRP CDS view.
…
@UI.lineItem: [{ importance: #HIGH, position: 10, }]
PurchaseDocumentItemImageURL;
@UI.lineItem: [{ importance: #HIGH, position: 20 }]
PurchaseDocument;
@UI.lineItem: [{ importance: #HIGH, position: 30 }]
PurchaseDocumentItem;
…
Enabling Quick Actions
To enable the Approve and Close status quick actions on the object page, you must
add the @UI.identification annotation to the PurchaseDocument field (Listing 4.34).
@UI: {
identification: [
{ type: #FOR_ACTION, dataAction: 'BOPF:APPROVE',
importance: #HIGH, label: 'Approve' },
{ type: #FOR_ACTION, dataAction: 'BOPF:CLOSE',
importance: #HIGH, label: 'Close' }],
…
}
PurchaseDocument;
Listing 4.34 Identification Annotation to Enable the Approve and Close Quick Actions in the
Object Page
176
第 177 页 / 共 465 页
4.6 Generating a List Report Template in SAP Web IDE Full-Stack
4.6 Generating a List Report Template in SAP Web IDE Full-Stack
The SAP Web IDE full-stack is the recommended IDE for developing state-of-the-art
SAP Fiori applications based on the SAPUI5 framework. This cloud-based IDE is acces-
sible via browser, and because it’s a service of the SAP Cloud Platform, you can easily
subscribe to it. SAP Web IDE full-stack provides very good support for creating front-
end project skeletons for freestyle SAP Fiori applications as well as for SAP Fiori ele-
ments applications. In the following subsections, we’ll use the SAP Web IDE to
generate our SAP Fiori elements-based list report and object page UI using the previ-
ously generated OData service of our app.
To create a list report and object page SAP Fiori elements app, choose File (cid:2) New (cid:2) Proj-
ect from Template, and select the list report application template within the SAP Fiori
Elements template category (Figure 4.35).
Figure 4.35 SAP Fiori Elements Templates Provided by the SAP Web IDE Full-Stack
177
第 178 页 / 共 465 页
4 Developing an SAP Fiori Elements List Report and Object Page
Next, provide a name for the project and some additional data that will be written to
the app descriptor of the application (Figure 4.36). You can later find this information
in the manifest.json file of the project. Click on Next.
Figure 4.36 Basic Information and App Descriptor Data When Creating a New Template-
Based List Report
On the next screen of the creation wizard, select the OData service of the app (Figure
4.37). For our purposes, we must first choose a SAP Gateway hub system where our
service has been activated. Subsequently, we can search for the service by its techni-
cal name and select it. Click on Next.
Our service provides two annotation files: the service metadata document, which can
be requested using the $metadata URL parameter, and an additional annotation file
containing our UI annotations (see Figure 4.38). This annotation file is provided by
the Catalog Service of the SAP Gateway hub system. You can also find this OData
annotation service in the dataSources object of the app descriptor (manifest.json file):
/sap/opu/odata/IWFND/CATALOGSERVICE;v=2/Annotations(TechnicalName='Z_C_
PURCHASEDOCUMENTLRP_CDS_VAN',Version='0001')/$value/
178
第 179 页 / 共 465 页
4.6 Generating a List Report Template in SAP Web IDE Full-Stack
Figure 4.37 Selecting the OData Service for the App
Figure 4.38 Annotation Files Provided by the Service
179
第 180 页 / 共 465 页
4 Developing an SAP Fiori Elements List Report and Object Page
On the last screen of the wizard, we must customize the template and provide our
two main entities as OData Collection and OData Navigation. Click Finish (Figure
4.39). To run the application, select the root folder of the project in the files pane, and
choose Run (cid:2) Run As (cid:2) Web Application from the context menu.
Figure 4.39 Customizing the Template by Choosing the Purchase Document Entity and the
Purchase Document Item Entity
Note
In general, OData annotations can be provided from three sources: the service meta-
data document, the Catalog Service using the annotation model of the OData ser-
vice, and local annotations. By default, SAP Web IDE will create a local annotation file
when generating the list report SAP Fiori elements application to render default fac-
ets on the object page. However, as we could provide all UI annotations via CDS
annotations, we must comment out or remove these annotations because they will
otherwise overwrite our CDS annotations.
Nevertheless, if it isn’t possible to provide certain annotations via CDS, the local
annotation file and its Annotation Modeler tool can be used instead. But keep in
mind that the OData annotation also must be supported and interpreted by the
respective SAP Fiori elements template application.
180
| Note In general, OData annotations can be provided from three sources: the service meta- data document, the Catalog Service using the annotation model of the OData ser- vice, and local annotations. By default, SAP Web IDE will create a local annotation file when generating the list report SAP Fiori elements application to render default fac- ets on the object page. However, as we could provide all UI annotations via CDS annotations, we must comment out or remove these annotations because they will otherwise overwrite our CDS annotations. Nevertheless, if it isn’t possible to provide certain annotations via CDS, the local annotation file and its Annotation Modeler tool can be used instead. But keep in mind that the OData annotation also must be supported and interpreted by the |
| respective SAP Fiori elements template application. |
第 181 页 / 共 465 页
4.7 Extending the User Interface
4.7 Extending the User Interface
You can further extend the generated list report and object page layout on the UI side
by using several predefined extension points; for instance, the list report defines an
extension point for adding additional table columns and the object page for adding
additional sections. In this case, UI parts aren’t defined using annotations but are
defined using actual XML fragment declarations and JavaScript SAPUI5 code as if you
were developing a freestyle SAPUI5 app. However, these coded extensions live within
strictly defined extension boundaries, which aren’t supposed to break the overall
design and structure of the SAP Fiori elements template. In the following, we’ll illus-
trate the concept of UI extension points by adding a custom column to the purchase
documents table. The column extension will visualize the budget share of a purchase
document using a radial micro chart control.
Note
UI extensions should be used with caution and only if the functionality can’t be
achieved by other means, for instance, annotations and app descriptor changes. UI
extensions are a greater intervention into the frontend project and increase the risk
of bugs and violations of the SAP Fiori design guidelines. For a full overview of all
extension possibilities, check the SAPUI5 SDK online documentation at http://bit.ly/
2Ob6yNg.
4.7.1 Implementing User Interface Extensions via Breakout
SAP Web IDE provides an extension wizard that you can open either from the top-
level menu bar by choosing File (cid:2) New (cid:2) Extension or from the context menu of the
project by choosing New (cid:2) Extension. However, you can also add extensions manu-
ally by modifying the manifest.json app descriptor file and creating the necessary
SAPUI5 controls and logic.
We’ll do the latter and manually create two SAPUI5 fragment declarations in a newly
created ext folder for extending the table columns (Figure 4.40). The ListReport-
ResponsiveTableColumns.fragment.xml contains the definition of the new column,
whereas the ListReportResponsiveTableCells.fragment.xml contains the definition of
the content, in our case, the RadialMicroChart control. Additionally, we’ll create a List-
ReportExtension.controller.js file and a formatter.js file as we want to calculate the
properties of the chart control dynamically based on the OverallPrice field of the
purchase document.
181
| Note UI extensions should be used with caution and only if the functionality can’t be achieved by other means, for instance, annotations and app descriptor changes. UI extensions are a greater intervention into the frontend project and increase the risk of bugs and violations of the SAP Fiori design guidelines. For a full overview of all extension possibilities, check the SAPUI5 SDK online documentation at http://bit.ly/ |
| 2Ob6yNg. |
第 182 页 / 共 465 页
4 Developing an SAP Fiori Elements List Report and Object Page
Figure 4.40 Overview of the Folder Structure and the
Required Files for Implementing the Column Extension
The column definition defined in the ListReportResponsiveTableColumns.fragment.xml
fragment looks as follows:
<core:FragmentDefinition xmlns:core="sap.ui.core" xmlns="sap.m">
<Column>
<Text text="Budget Share"/>
<customData>
<core:CustomData key="p13nData" value='\
{"columnKey": "TestKey", "columnIndex" : "200"}'/>
</customData>
</Column>
</core:FragmentDefinition>
Using the CustomData tag and the p13nData attribute, we enable the column for per-
sonalization. It can, therefore, also be configured using the personalization dialog of
the table like the other fields provided by the backend. The cell definition defined in
the ListReportResponsiveTableCells.fragment.xml fragment looks as follows:
<core:FragmentDefinition xmlns:core="sap.ui.core" xmlns="sap.m" xmlns:micro=
"sap.suite.ui.microchart"
xmlns:app="http://schemas.sap.com/sapui5/extension/sap.ui.core.CustomData/1">
182
第 183 页 / 共 465 页
4.7 Extending the User Interface
<FlexBox height="70px" width="70px">
<layoutData>
<FlexItemData maxHeight="70px"/>
</layoutData>
<micro:RadialMicroChart percentage="{ path: 'OverallPrice',
formatter: '.formatter.calculatePercentage' }" app:name="radial"
press="press" valueColor="{ path: 'OverallPrice', formatter:
'.formatter.calculateCriticality' }"/>
</FlexBox>
</core:FragmentDefinition>
We define the RadialMicroChart as the content of the new extension column and cal-
culate the percentage and valueColor properties of the control using the formatter’s
calculatePercentage and calculateCritcality functions. The implementation of the
formatter is shown in Listing 4.35. In the calculatePercentage function, we calculate
what percentage of the total budget the current purchase document would consume.
In the calculateCritcality function, we once again calculate the criticality of the
OverallPrice value; however, this time it’s calculated on the UI side.
sap.ui.define([], function () {
"use strict";
var TOTAL_BUDGET = 10000;
return {
calculatePercentage: function (nOverallPrice) {
var percentage = Math.round((nOverallPrice / TOTAL_BUDGET) * 100);
return percentage > 100 ? 100 : percentage;
},
calculateCriticality: function (nOverallPrice) {
if (nOverallPrice <= 1000) {
return "Good";
} else if (nOverallPrice > 1000 && nOverallPrice < 5000) {
return "Critical";
} else {
return "Error";
}
}
};
});
Listing 4.35 Implementation of the Formatter for Dynamically Calculating the Percentage
and Criticality Based on the OverallPrice Field
183
第 184 页 / 共 465 页
4 Developing an SAP Fiori Elements List Report and Object Page
To enable the formatter for usage within the cell content definition fragment, we
must add it to the extension controller as an object property (Listing 4.36).
sap.ui.define([
"fiori/manage/purchase/documents/purchasedocumentslrp/model/formatter"
], function (formatter) {
"use strict";
return sap.ui.controller(
"fiori.manage.purchase.documents.purchasedocumentslrp.ext.controller.
ListReportExtension", {
formatter: formatter
});
});
Listing 4.36 Controller Implementation Including the Formatter as an Object Property to
Enable It for Usage within the Content Definition of the Extension Column
Finally, to enable the extension implementation, we must define the column exten-
sion and the custom controller in the app descriptor (manifest.json) file (Figure 4.41).
Figure 4.41 App Descriptor (manifest.json) Changes to Enable the Column and Controller
Extension
4.7.2 Adding a QUnit Unit Test
When implementing UI extensions and introducing logic implemented in JavaScript
and SAPUI5, you should always cover this logic with a unit test. QUnit is the recom-
184
第 185 页 / 共 465 页
4.7 Extending the User Interface
mended unit testing framework for implementing unit tests for SAPUI5 applications
because it’s a powerful and easy-to-use unit testing framework included with the
SAPUI5 SDK. To add unit tests for our formatter, we first will add a unit test folder
below the already existing test folder which we’ll name unit (Figure 4.42).
Figure 4.42 Folder Structure for Unit Tests
Additionally, we’ll add a folder called model to reflect the folder structure of the
actual implementation and the corresponding test file, which we’ll also call format-
ter.js. The formatter unit test will create several test cases covering the corner cases of
our logic implemented in calculateCriticality and calculatePercentage. You can
see an excerpt of the unit test in Listing 4.37.
sap.ui.define(["fiori/manage/purchase/documents/purchasedocumentslrp/model/
formatter"],
function (formatter) {
"use strict";
QUnit.module("Calculate Criticality");
QUnit.test("If the overall price is less than or equal to 1000 the criticality
is formatted to Good", function (assert) {
assert.strictEqual(formatter.calculateCriticality(1000), "Good");
});
…
QUnit.module("Calculate Percentage");
QUnit.test("With an overall price of 10000 and a total budget of 10000 the bud
get utilization should be 100%", function (assert) {
185
第 186 页 / 共 465 页
4 Developing an SAP Fiori Elements List Report and Object Page
assert.strictEqual(formatter.calculatePercentage(10000), 100);
});
…
Listing 4.37 Excerpt of the Formatter Unit Test
In the unit folder, we’ll create an HTML file called unitTests.qunit.html, which will start
the tests and display the test results.
The content of the unitTests.qunit.html file is shown in Listing 4.38. We set the data-
sap-ui-resourceroots property here to link the namespaces to the respective imple-
mentation and test root folders and include the formatter test case. The test result
will be inserted dynamically at runtime in the body part of the HTML document. The
tests can be run by choosing Run (cid:2) Runs As (cid:2) Unit Test from the context menu of the
unitTests.qunit.html file. The output of a test run is shown in Figure 4.43.
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<script id="sap-ui-bootstrap"
src="../../resources/sap-ui-core.js"
data-sap-ui-theme="sap_belize"
data-sap-ui-noConflict="true"
data-sap-ui-resourceroots='{
"fiori.manage.purchase.documents.purchasedocumentslrp" :"../../",
"test.unit": "./"
}'></script>
<script language="javascript">
jQuery.sap.require("sap.ui.qunit.qunit-css");
jQuery.sap.require("sap.ui.thirdparty.qunit");
jQuery.sap.require("sap.ui.qunit.qunit-junit");
jQuery.sap.require("sap.ui.qunit.qunit-coverage");
sap.ui.require(["test/unit/model/formatter"]);
</script>
</head>
<body>
<div id="qunit"></div>
</body>
</html>
Listing 4.38 QUnit Test File That Will Display the Results of the Test
186
第 187 页 / 共 465 页
4.9 Summary
Figure 4.43 Output of the QUnit Unit Test Run
4.8 List Report Application versus Worklist Application
At first sight, the SAP Fiori elements list report and worklist templates look very sim-
ilar. Both templates have a table on their start page and offer navigation to an object
page to inspect the table entries in detail. Therefore, we could easily reuse our OData
service to create a worklist application instead. However, the main difference is that
the list report template provides a powerful filter bar that allows searching, filtering,
and acting on large data sets unlike the worklist template, which doesn’t have a sepa-
rate filter bar at all. Consequently, the worklist application will only display items a
certain user must process and therefore doesn’t require sophisticated filtering of
table entries as the work items are supposed to be already prefiltered based on the
user’s tasks.
4.9 Summary
In this chapter, we developed a SAP Fiori elements list report application from
scratch. We started the development from the bottom up by creating the database
tables for our main entities: purchase document and purchase document item. On
top of the database tables, we put a VDM according to the SAP S/4HANA development
187
第 188 页 / 共 465 页
4 Developing an SAP Fiori Elements List Report and Object Page
guidelines starting with reusable basic interface views over to composite interface
views and consumption views. We added several calculated fields to our composite
interface and consumption views and tested the calculation logic using ABAP Unit
and the CDS Test Double Framework. Additionally, we added transactional capabili-
ties to our application by generating a BOPF business object from our CDS data model
and implemented a quick action for approving purchase documents. Subsequently,
we created an OData service using Auto-Exposure and added CDS UI annotations to
our consumption views’ metadata extension files to configure the list report tem-
plate according to our design. Finally, we generated the list report and object page
applications using SAP Web IDE. As a last step, we extended the standard list report
template by implementing a calculated column extension. We used QUnit unit tests
to safeguard the JavaScript calculation logic. In the next chapter you will get to know
about another SAP Fiori Elements application type called overview page (OVP).
188
第 189 页 / 共 465 页
Chapter 5
Developing an Overview Page
In this chapter, you’ll learn about building an overview page (OVP)
application and we will learn about how different types of cards are
used in an overview page to represent the data in different formats.
For this OVP application, we’ll build a set of Core Data Services (CDS) views built on
top of the purchase document and purchase document item tables we used in Chap-
ter 4 to build a list report application. Because we went with using automatic genera-
tion of OData services using CDS view annotations in the previous chapter, we’ll
create the OData service manually in this chapter. We’ll also create individual con-
sumption views in the backend and use those CDS views in the OVP template in SAP
Web IDE to generate multiple types of cards for the OVP.
5.1 Core Data Services Views
As in the previous chapter, we’ll take a bottom-up approach to build several layers of
CDS views with a basic interface layer on top of database tables. Because we’ve
already created the database tables in the previous chapter, we don’t have to start
from the very beginning.
Before we start building the views, lets decide what we need to show in our overview
page (OVP). If you remember the guidelines mentioned in Chapter 2, we should only
use OVPs for certain scenarios. So, our plan is to design an OVP that will have multi-
ple cards should give the user an overall view into the different aspects of the under-
lying data and should help the user identify some key aspects in making decisions.
The apps should show the underlying data in different formats, such as charts or
tables, so that the user can easily analyze the information. Following are the few cards
that should fit those requirements.
(cid:2) Analytical card
Displays the overall number of documents based on priority and status in the
form of a chart.
189
第 190 页 / 共 465 页
5 Developing an Overview Page
(cid:2) Table card
Gives a summary of pending documents at the item level.
(cid:2) List card (standard type)
Gives the approver an overview of the number of documents pending for
approval.
(cid:2) List card (bar type)
Gives a summarized view of whether the purchasing documents are within the
allowed budget or not.
5.1.1 Creating a Simple Core Data Services View
Now that we have an idea of what information is needed to be displayed on the app,
let's discuss the CDS views that we need to build the app. An OVP requires separate
CDS views for each card as well as a dedicated CDS view for the filter bar. In Figure 5.1,
we’ve made a design approach that includes the number of consumption views
required to generate the OVP and the cards.
Shell Bar
Header Title
Header Content – Filter Bar
List Card (Bar)
List Card
Analytical
Card Table Card (Standard)
Z_C_PurchaseDocBudgetOVP
Z_C_PurchaseDocumentOVP
Z_C_PurchaseDocumentPendingOVP
Z_C_PurchaseDocsforApprovalOVP Z_C_PurchaseDocumentFiltersOVP
Figure 5.1 CDS Views Required for the OVP
190