README

ui5-middleware-lrep-flex

Custom UI5 middleware extension for handling requests to SAPUI5 Flexibility Services / Layered Repository.

Prerequisites

Make sure your project is using the latest UI5 Tooling.

Getting started

Install

Add custom middleware

Add the custom middleware as a devDependency to your project.

With yarn:

yarn add -D ui5-middleware-lrep-flex

Or npm:

npm i -D ui5-middleware-lrep-flex

Additionally the custom middleware needs to be manually defined as a ui5 dependency in your project's package.json:

{
  "ui5": {
    "dependencies": [
      "ui5-middleware-lrep-flex"
    ]
  }
}

Register

server:
  customMiddleware:
  # layered respository / flexibility
  - name: ui5-middleware-lrep-flex
    afterMiddleware: compression
    configuration:
      # enable middleware
      enable: true
      # show debug logs
      debug: true
      # handle e.g. GET /sap/bc/lrep/flex/data/bookshop.ui.Component?appVersion=1.0.0&sap-language=en
      component:
        # path for .change files
        changesPath: webapp/changes
        # data to be merged to each .change file
        changeData:
          support:
            user: "SAP"
          validAppVersions:
            creation: "1.0.0"
            from: "1.0.0"
            to: "1.0.0"
        # data to be merged and sent for each response
        data:
          settings:
            isKeyUser: true
            isAtoAvailable: false
            isProductiveSystem: false

Supported Requests

As of now the following requests are being handled by the custom middleware.

More handlers might be added in the future.

Get component data

Example request: GET /sap/bc/lrep/flex/data/bookshop.ui.Component?appVersion=1.0.0&sap-language=en

E.g. Fiori Elements applications will trigger this request amongst other things to fetch any UI Adaption changes done for the application.

Normally these .change files will be stored under webapp/changes.

The custom middleware will collect and read all .change files and will send the appropriate response:

{
  "changes": [
    {
      // content of first .change file
    },
    {
      // content of second .change file
    },
    // ...
  ]
}

Additional remarks:

Handling this request server-side in the custom middleware eliminates the need for any client-side handling and workarounds e.g. changes_preview.js.

To make sure your changes are being applied correctly simply include library sap.ui.fl in data-sap-ui-libs when bootstraping your app:

<!DOCTYPE HTML>
<html>
<head>
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <!-- i18n title -->
    <title>{{appTitle}}</title>
  <!-- load ushell config -->
  <script id="sap-ushell-config" src="./sap-ushell-config.js"></script>
  <!-- bootstrap ushell sandbox -->
    <script id="sap-ushell-bootstrap" src="/test-resources/sap/ushell/bootstrap/sandbox.js"></script>
  <!-- bootstrap the UI5 core library -->
    <script
    id="sap-ui-bootstrap"
    src="/resources/sap-ui-core.js"
    data-sap-ui-libs="sap.ui.core, sap.m, sap.suite.ui.generic.template, sap.ushell, sap.ui.fl"
    data-sap-ui-resourceroots='{
      "bookshop.ui": "../"
    }'
    data-sap-ui-onInit="module:bookshop/ui/test/flpSandboxMockServer"
    data-sap-ui-theme="sap_fiori_3_dark"
    data-sap-ui-compatVersion="edge"
    data-sap-ui-async="false"
    data-sap-ui-language="en-US"
    data-sap-ui-frameOptions="allow">
    </script>
</head>
<body id="content" class="sapUiBody">
  <!-- content will rendered here -->
</body>
</html>

You should also include the sap.ui.fl library for development in your ui5.yaml when consuming SAPUI5 libraries:

specVersion: "2.2"
metadata:
  name: bookshop.ui
type: application
framework:
  name: SAPUI5
  version: "1.82.0"
  libraries:
    - name: sap.m
    - name: sap.ui.core
    - name: sap.suite.ui.generic.template
    - name: sap.ushell
      development: true
    - name: sap.ui.fl
      development: true
    - name: themelib_sap_fiori_3
      development: true

Additional configuration

The custom middleware accepts the following configuration options:

name	type	description	mandatory	default
`enable`	boolean	enable/disable middleware	no	`true`
`debug`	boolean	enable/disable debug logs	no	`false`
`component`	object	configuration for component request handler	no	`{}`
`component.changesPath`	string	path of `.change` files	no	`webapp/changes`
`component.changeData`	object	data to be merged to each `.change` file	no	`{}`
`component.data`	object	data to be merged and sent for each response	no	`{}`

Usage no npm install needed!