@sap-ux/preview-middleware v0.13.27

@sap-ux/preview-middleware

The @sap-ux/preview-middleware is a Custom UI5 Server Middleware for previewing an application in a local Fiori launchpad . It can be used either with the ui5 serve or the fiori run commands. It hosts a local Fiori launchpad based on your configuration as well as offers an API to modify flex changes in your project. The API is available at /preview/api and additional client code required for the preview is available at /preview/client.

When this middleware is used together with the reload-middleware, then the order in which the middlewares are loaded is important. The reload-middleware needs to be loaded before the preview-middleware. Hence the configuration in the ui5.yaml needs to look e.g. like this:

- name: reload-middleware
  afterMiddleware: compression
- name: preview-middleware
  afterMiddleware: reload-middleware

Configuration Options

flp.apps

Array of additional application configurations: | Option | Type | Default Value | Description | | ------------------------ | -------- | -------------- | ------------------------------------------------------------------------------------------------------------- | | target | string | | Target path of the additional application | | local or componentId | string | | Either a local path to a folder containing the application or the componentId of a remote app is required | | intent | | | Optional intent to be used for the application | | intent.object | string | (calculated) | Optional intent object, if it is not provided then it will be calculated based on the application id | | intent.action | string | preview | Optional intent action |

adp.target

rta.editors

test

Usage

The middleware can be used without configuration. However, since the middleware intercepts a few requests that might otherwise be handled by a different middleware, it is strongly recommended to run other file serving middlewares after the preview-middleware e.g. backend-proxy-middleware and ui5-proxy-middleware (and the corresponding middlewares in the @sap/ux-ui5-tooling). Example: ./test/fixtures/simple-app/ui5.yaml

Minimal Configuration

With no configuration provided, the local FLP will be available at /test/flp.html and the log level is info.

server:
  customMiddleware:
  - name: preview-middleware
    afterMiddleware: compression

Different Path and Debugging enabled

With this configuration, the local FLP will be available at /test/myFLP.html and the log level is debug.

server:
  customMiddleware:
  - name: preview-middleware
    afterMiddleware: compression
    configuration:
      flp: 
        path: /test/myFLP.html
      debug: true

Additional Applications

If you want to test cross application navigation, then you can add additional applications into the local FLP. With this configuration, an application that is locally available in ../local-folder will be available at /apps/other-app and will also be added as tile to the local FLP as well as one of the UI5 sample apps will be bound to the intent TheOther-preview.

server:
  customMiddleware:
  - name: preview-middleware
    afterMiddleware: compression
    configuration:
      apps:
        - target: /apps/other-app
          local: ../local-folder
          intent: 
            object: TheLocal
            action: preview
        - target: /test-resources/sap/ushell/demoapps/AppNavSample
          componentId: sap.ushell.demo.AppNavSample
          intent: 
            object: TheOther
            action: preview

Runtime Adaptation Support

If you want to create variants as part of your application, then you can create an additional mount point allowing to created and edit variants.

server:
  customMiddleware:
  - name: preview-middleware
    afterMiddleware: compression
    configuration:
      rta:
        layer: CUSTOMER_BASE
        editors:
          - path: /test/variant-editor.html

Test Suites

If you want to also generate generic test suites and test runners for QUnit or OPA5 tests then you can use the following minimum configurations

server:
  customMiddleware:
  - name: preview-middleware
    afterMiddleware: compression
    configuration:
      test:
        - framework: QUnit
        - framework: OPA5

Adaptation Project

If you want to use the middleware in an adaption project, the additional adp object needs to be configured. This example would preview a local adaptation project merged with its reference application from the target system at http://sap.example and it will ignore certification validation errors. For adaptation projects, it is also recommended to add the rta configuration allowing to edit the project.

server:
  customMiddleware:
  - name: preview-middleware
    afterMiddleware: compression
    configuration:
      adp: 
        target: 
          url: http://sap.example
        ignoreCertErrors: true
      rta:
        editors:
          - path: /test/adaptation-editor.html
            developerMode: true

Programmatic Usage

Alternatively you can use the underlying middleware fuction programmatically, e.g. for the case when you want to incorporate the preview-middleware functionality in your own middleware.

import { FlpSandbox } from '@sap-ux/preview-middleware';
const flp = new FlpSandbox(flpConfig, rootProject, middlewareUtil, logger);
const files = await resources.rootProject.byGlob('/manifest.json');
flp.init(JSON.parse(await files[0].getString()));

return flp.router

• flpConfig - the middleware configuration
• rootProject - Reader to access resources of the root project
• middlewareUtil - MiddlewareUtil of the UI5 server
• logger - Logger instance for use in the middleware.