Latest Update November 2020: 

It’s hard to believe that 4 years have passed since I first started blogging on SAP Fiori elements.

Since then it has grown from strength to strength. SAP Fiori elements apps are now the:

• Preferred choice for SAP Fiori apps delivered for SAP S/4HANA
  • As at November 2020 nearly 900 of the more than 2K apps available are SAP Fiori elements app
• Preferred and recommended choice for efficient development of your own custom-built apps
• Preferred build approach for many of our customers… see the SAP TechEd 2020 session: Yorkshire Water uses SAP Fiori Elements to build Fiori apps quickly

The tooling has also changed from SAP Web IDE on SAP Cloud Platform Neo, to the next generation tooling SAP Fiori Tools.  SAP Fiori Tools are an extension of SAP Business Application Studio on SAP Cloud Platform Cloud Foundry that guide you through creating your own SAP Fiori elements apps – and they can be run offline on VSCode too.

So it’s time for this blog post to step gracefully aside and instead refer you to the current best resources for Fiori elements, including:

• SAP Community topic for Fiori elements – get the latest resources, ask questions, and swap experiences with other customers, partners, independents, and SAP employees
• The official documentation on SAP Help Portal: Developing Apps with SAP Fiori elements
  • You can also find this documentation via the SAPUI5 SDK at https://ui5.sap.com > Documentation > Developing Apps with SAP Fiori elements
• The video playlist on Youtube: Getting started with SAP Fiori elements playlist
• The Tutorials for SAP Fiori Tools on https://developers.sap.com

One last big hint: One of the most beneficial additions to the official documentation is the SAP Fiori elements feature map which explains what is available per floorplan for your SAPUI5 version – definitely worth a read!

But hey, all knowledge has value so if you want to read how this used to work in the SAP Web IDE… read on!

*****

In Fiori Elements – Develop a List Report Basic Approach we looked at the simplest way to create a List Report using an OData service based on a purpose built CDS view with all of the annotations pre-set.  In this blog we look at alternate approach when you have an OData service without any pre-set annotations.  You can also use this approach to override or supplement pre-set annotations.

Find other Fiori Elements blogs on the Fiori Elements wiki

What are annotations?

In my first blog I described them as … “comments on the OData service that provides the data”.

The official OData site gives them a formal definition as:

“Metadata annotations can be used to define additional characteristics or capabilities of a metadata element, such as a service, entity type, property, function, action or parameter.”

I find it more helpful to think of them as adding formalised semantic meaning to OData entities. In other words the annotations describe the purpose and intent of the OData entity and its attributes in a way that can be used directly by programs (and, happily, humans).

As mentioned in previous blogs, annotations are an optional part of OData.  The available annotations are described using an OData vocabulary.  For example, SAP has a vocabulary of all annotations that can be used in ABAP CDS views.  Some of these annotations are UI annotations that we can use to build our List Report.  Other annotations have other purposes such as @OData.Publish:true which exposes a CDS view as an OData Service. When it comes to UI Annotations, there are quite a lot of them… so we’ll start with a focus on the essentials for List Reports.

Creating a Fiori Element List Report with Annotations XML

Before we start, it’s worth noting that while its UI annotations let us control most of the List Report, not everything can be controlled by UI annotations. Certain features depend on what the OData Service itself provides, e.g. we can only provide a keyword search in the List Report Filter bar if the OData Service EntitySet contains the semantic marker sap:searchable=”true”. Features such as create, update, delete are provided in a similar way.

So how does using an annotations XML file change our process for creating a List Report which in Fiori  Elements – How to develop a List Report – Basic Approach as:

1. Prepare the OData service
2. Prepare the UI Annotations
3. Create the Fiori App using the Fiori Elements List Report template

The pre-requisites are still the same, and the process itself is essentially the same, it’s just a slight change in the order of the steps:

1. Prepare the OData service
2. Create the Fiori App using the Fiori Elements List Report template
3. Prepare the UI Annotations

So to show how this works, we’ll start with an OData Service without any UI annotations.  To demonstrate that this is really the only difference we will again use an OData Service based on a CDS view, although as mentioned in my previous blog, CDS views are not a pre-requisites – just very easy to use.

This time our OData Service is similar to our previous example but without any UI annotations and looks like this:

Creating the Fiori App in the HCP Web IDE using the Fiori Elements List Report wizard works exactly the same way. The only difference is which service and entity we select for the report. Now if you are using a SAP system that supports annotations it will still show you an annotation file, it’s just that the file will be generated with a  very basic XML structure.

Because there are no annotations yet, if you run the Component.js file of your app it will look something like this:

Working with the Annotations XML file

To work with our local annotations file we first need to check we have one. If you have used the wizard then it should exist already, but not everyone has access to HCP Web IDE or Personal Web IDE, so let’s review again where this lives in the recommended SAPUI5 app structure.

In our app we should see a folder called “annotations”. This should be a sub-folder of “webapp”.  If not we can always create one, e.g. using the context menu of folder “webapp” and selecting New > Folder.

Next we check there is a file called annotations.xml in our project’s annotations folder. If not we can create one using the context menu of folder “annotations” and selecting New > Annotation File.

Tip: It’s important to use the New > Annotation file wizard, and not just create the file using New > File.  The Annotation file wizard will not only create an annotations xml file, it will fill it with the basic edmx tags needed to start annotating. This is an example of an annotations.xml file generated this way:

The annotation file wizard will also update the manifest.json file to make sure our app:

1. Knows where the annotation file sits in the project hierarchy and exactly what the file is called
2. Knows where to find text resources (i18n.properties) related to your annotations file
3. Links the OData Service to the related annotation xml file

As a reminder, we looked at the manifest.json file and its contents in the Fiori  Elements – How to develop a List Report – Basic Approach blog.

Tip: The annotations file doesn’t need to be called annotations.xml – although it does need to be a XML file.  If we use a different file name then we need to adjust the manifest.json file to match.

We can edit the annotations file directly using the Code Editor or, in the HCP Web IDE, we can use the Annotation Modeler tool. The Annotation Modeler uses a HCP Web IDE plugin so it is only available in the HCP Web IDE, so it’s always worth knowing the XML format itself.  In this blog for simplicity we will show the annotation modeler and related XML snippets.

You’ll find XML snippets for the different annotations in the SAPUI5 SDK in the section Developing Apps with SAP Fiori Elements > Annotations Relevant for List Reports and Object Pages, and Annotations Relevant for List Reports.

Annotations of the Fiori Element List Report

We can see in the SAPUI5 SDK that there are several UI annotations relevant to the List Report, but fortunately there are only 3 we need to create a basic List Report and these are:

• UI.HeaderInfo – for the list table header
• UI.LineItem – for the list table contents
• UI.SelectionFields – for the filter bar fields

They relate to the List Report as follows:

Before we add any annotations our annotations.xml file looks like this in the annotation modeler.

In the Code Editor, if we’ve used the Fiori Elements List Report wizard, the relationship to our OData Service will already be added to the  tag of our annotations.xml file and will look like this:

All of our following annotations will need to be placed within a <Schema> tag for our OData Entity Set within the <edmx:DataServices> tag like this:

We use the + icon in the action columns to add extra annotations.

Adjusting the UI.HeaderInfo Annotations

The easiest annotation to add is the UI.HeaderInfo that adds the description and count to the table header of our List Report.  All we need to do is to enter the mandatory fields TypeName and TypeName Plural.  We can see in the Key Information column that these are immediately added to i18n property files.

It’s also mandatory to enter a value for the Title annotation which is a child of UI.HeaderInfo. This annotation will actually be used for the related Object Page which will we cover in a future blog.

In the code editor these annotations will look like this:

Adjusting the UI.LineItem Annotations

The UI.LineItem annotations denote which fields should be columns in our list report table.  There are different types of columns we can use – text, numbers, date/time, amount with currency, quantity with unit, urls, buttons, rating stars, progress bars, etc.  Once again we start with the simplest approach which is to use simple typed data fields, such as text and number fields.  For this we select the + action next in the UI.LineItem and choose the child annotation DataField.

In the DataField annotation we use the Value dropdown select the matching entity attribute and add a Label for the column header. The annotation modeler automatically adds the Labels to the @i18n properties file, or we can select an existing text from the file for our Label. We repeat this for as many columns as we want to add.

In the code editor these annotations will look like this:

Adjusting the UI.SelectionFields Annotations

We add the fields we want in our filter bar in the UI.SelectionFields annotations.  We use the SelectionFields dropdown to select attributes of our EntitySet. We use the Add Path option to add more filter fields.

In the code editor these annotations will look like this:

Running the app

Having saved all the UI annotations we have added, we can now run our App from the Component.js file. It should look like this:

Once again it’s a fully functioning production quality List Report app, complete with personalization settings (check out the gear wheel icon at the top right of the table) so users can adjust the filters, sort order, and groupings.

Basic vs. Alternate Approach

So which approach is preferred – basic approach or local annotations? Certainly if you have an environment capable of producing annotated CDS views and you are creating views explicitly for a given list report it makes sense to keep the annotations aligned against the CDS view. Otherwise local annotations work just fine.

In the next blog we’ll look at how we can make the list report even more useful.  We can control features such as the table type, single or multi-selection of rows, filter variant management, and default sort order.

We can also add some graphical visualizations to make the information in our report easier to understand such as thumbnail images, status icons, rating stars and progress bars.   These are techniques we’ll be able to reuse when we look at the Object Page in a future blog.