UI5ers Buzz #51: UI5 Tooling 2.0: How to develop a...

pmuessig · ‎2020 Apr 15

Introduction

On April 1^st I talked about the “UI5 Tooling – a modern CLI-based development experience” in a SAP Community call. A week later, on April 7^th I published the blog post “UI5 Tooling: a modern development experience for UI5!” which demonstrates the capabilities of the UI5 Tooling how we can consume UI5 library dependencies locally and how we can use custom middlewares to improve the overall UI5 development experience. This time, I want to focus on the availability of SAPUI5 on NPM and how we can utilize this to develop and run an SAP Fiori elements application locally.

SAPUI5 from NPM!

The biggest benefit of the UI5 Tooling 2.0 is the consumption of the SAPUI5 library dependencies from NPM. merlin.beutlberger#about explains the new features of the UI5 Tooling 2.0 in his blog post “The UI5 Tooling and SAPUI5 – The Next Step”. Thanks to the awesome work of the UI5 Tooling team, we can now develop SAPUI5 applications locally. We can consume the sap.suite.ui.generic.template library to build and develop SAP Fiori elements applications locally and also consume the sap.ushell library to make the application running in the SAP Fiori launchpad sandbox. Within this blog post, I will focus on creating an SAP Fiori elements application in SAP Web IDE and run it locally with the UI5 Tooling.

Prerequisites

As the UI5 Tooling is based on Node.js. We need to ensure that at least Node.js version 10 is installed and configured properly.

Step 1: Create an SAP Fiori elements application

In the first step, we create an SAP Fiori elements application based on the List Report Application template. This has to be done in SAP Web IDE by using the template wizard.

Follow these steps to create a List Report Application:

Open SAP Web IDE

"File" > "New" > "Project from template"

Select environment "Neo" (as this affects the datasource URL relevant for the proxy)

Select category "SAP Fiori Elements"

Select template "List Report Application"

Enter your project name, title and namespace

In the data connection step (prerequisite: setup a destination to Northwind OData Services first), select the Northwind OData Services as "Service URL", use the "Relative URL": /V2/Northwind/Northwind.svc/) and press "Test".

Skip the annotation selection step, just press "Next"

In the template customization step, select the Object Collection: Customers, OData Navigation: Orders, OData Sub Navigation: Order_Details.

Finish

Step 2: Create the annotation file

As second step, we need to create a simple annotation file for our SAP Fiori elements application. Therefore, follow these steps:

Create the folder annotations in the webapp folder

Use the context menu on the annotations folder and select "New" > "Annotation File"

Just keep the default settings for the annotation file and press "Next" and "Finish"

Create a LineItem annotation with the DataFields: CustomerID, CompanyName and ContactName and the SelectionFields annotation with the Items: CustomerID, CompanyName and ContactName

Feel free to add more annotations. 🙂 Finally, the simple annotation file should look like this:

We can test the annotations file by running the SAP Fiori elements application with the SAPUI5 Visual Editor. The application should look like this (select the project in the project explorer and use the context menu on the project folder to launch the SAPUI5 Visual Editor):

That's all we need to do in the SAP Web IDE. Let's go local...

Step 3: Download and prepare the SAP Fiori elements application

After the SAP Fiori elements application has been created, select it in the project explorer, export it from SAP Web IDE and unzip it locally in your file system. As a first step locally, we validate whether we need to update the project dependencies of the created UI5 application. To update the project dependencies, we can use the open-source tool npm-check-updates. This tool can be installed via:

npm install -g npm-check-updates

After the installation of the tool, we can run:

ncu -u

to upgrade the project dependencies in the package.json. Once the project dependencies are upgraded, run:

npm install

to prepare the project for a first run. The project can be started with the command:

npx ui5 serve -o test/flpSandbox.html

Although the development server starts technically, there are a few things missing to make the SAP Fiori elements application to run properly (e.g. the SAPUI5 resources).

Step 4: Consume SAPUI5 library dependencies from NPM

Now, we are configuring the application to consume the SAPUI5 library dependencies from NPM. Therefore, we modify the ui5.yaml to use the specVersion: 2.0:

specVersion: '2.0'

metadata:

  name: mylistreport

type: application

[…]

As next step, we add the framework dependency to SAPUI5 by running the following command:

npx ui5 use sapui5@latest

Once the framework dependency is added, we can include the required SAPUI5 libraries with the following command (make sure to grab the whole line => it's long 😉 😞

npx ui5 add sap.ui.core sap.m sap.ushell sap.collaboration sap.ui.generic.app sap.suite.ui.generic.template themelib_sap_fiori_3

This will add the sap.ui.core, sap.m, sap.ushell, sap.collaboration, sap.ui.generic.app, sap.suite.ui.generic.template and the themelib_sap_fiori_3 as UI5 library dependencies to the project and the two commands above will create the following section in the ui5.yaml:

framework:

  name: SAPUI5

  version: "1.76.1"

  libraries:

    - name: sap.collaboration

    - name: sap.m

    - name: sap.suite.ui.generic.template

    - name: sap.ui.core

    - name: sap.ui.generic.app

    - name: sap.ushell

    - name: themelib_sap_fiori_3

After starting the development server with:

npx ui5 serve -o test/flpSandbox.html

the SAPUI5 resources are loaded from the framework dependencies configured in the ui5.yaml. We will see the following screen:

Now the SAP Fiori elements application is starting up and you can go ahead to configure the proxy to access the Northwind OData Service.

Step 5: Setting up a proxy to tunnel the Northwind OData Service

To access the Northwind OData Service in the SAP Fiori elements application, we can simply use the simple proxy middleware from the UI5 Ecosystem Showcase. It can be installed as a dev dependency by running the following command:

npm install ui5-middleware-simpleproxy --save-dev

Afterwards, we need to add the ui5-middleware-simpleproxy as ui5/dependencies in the package.json:

  "ui5": {

    "dependencies": [

      "@sap/ui5-builder-webide-extension",

      "ui5-middleware-simpleproxy"

    ]

  },

Now, we need to open the ui5.yaml and add the following configuration before the framework section:

[…]

server:

  customMiddleware:

  - name: ui5-middleware-simpleproxy

    mountPath: /Northwind/V2/Northwind/Northwind.svc/

    afterMiddleware: compression

    configuration:

      baseUri: https://services.odata.org/V2/Northwind/Northwind.svc/

framework:

  name: SAPUI5

  version: "1.76.1"

[…]

This configuration ensures that requests to /Northwind/V2/Northwind/Northwind.svc/ are proxied to https://services.odata.org/V2/Northwind/Northwind.svc/.

Step 6: Validate that the SAP Fiori elements application runs locally

The next step is to validate that the SAP Fiori elements application runs locally. Therefore, we first ensure that all project dependencies are installed by running:

npm install

Afterwards, we can start the development server by executing:

npx ui5 serve -o test/flpSandbox.html

This will open our preferred browser and the SAP Fiori launchpad will come up with a tile for our SAP Fiori elements application. If we click on this tile, our application will start, and the data will be loaded from the Northwind OData Service.

Step 7: Add the livereload middleware

With the livereload middleware you can achieve a click and refresh behavior while developing. The middleware is watching the changes of the sources in the file system. Once a source file has been modified the livereload middleware refreshes the application in the browser.

Add the livereload middleware with the following command:

npm install ui5-middleware-livereload --save-dev

Afterwards in the package.json ensure to list the ui5-middleware-livereload in the ui5/dependencies:

  "ui5": {

    "dependencies": [

      "@sap/ui5-builder-webide-extension",

      "ui5-middleware-simpleproxy",

      "ui5-middleware-livereload"

    ]

  },

Afterwards, in the ui5.yaml just include the livereload middleware configuration next to the simpleproxy middleware configuration to the server/customMiddleware section:

[…]

server:

  customMiddleware:

  - name: ui5-middleware-simpleproxy

    mountPath: /Northwind/V2/Northwind/Northwind.svc/

    afterMiddleware: compression

    configuration:

      baseUri: https://services.odata.org/V2/Northwind/Northwind.svc/

  - name: ui5-middleware-livereload

    afterMiddleware: compression

    configuration:

      ext: "xml,json,properties"

      path: "webapp"

framework:

  name: SAPUI5

  version: "1.76.1"

[…]

The next time when you start the development server by running the following command:

npx ui5 serve -o test/flpSandbox.html

the livereload middleware is watching your file system and in case of changes it will refresh your browser (remark: in case you face issues with livereload, maybe your html page was cached before, just ensure to reload the html page properly).

Conclusion

As we can see, we can develop an SAP Fiori elements application locally with the UI5 Tooling. The SAPUI5 library dependencies are available locally and can be consumed. However, local SAP Fiori elements application development still feels a bit bumpy! Within SAP Web IDE, due to the availability of the Annotation Modeler and the SAPUI5 Visual Editor we have quite nice visual tools which support us to develop SAP Fiori elements applications. For local development these visual tools really missing. But for the purists among us who like to develop directly in the annotation files with the angle brackets, this could be nonetheless an interesting alternative. Enjoy…