@bluewardai/ui5-loading

v1.0.5

Published

2 months ago

Reusable global and scoped loading overlay library for UI5 applications

0High
0Medium
0Low

rendez0829

ui5 sapui5 loading busy-indicator

Blueward UI5 Loading

@bluewardai/ui5-loading은 SAPUI5 애플리케이션에서 공통으로 사용할 수 있는 Loading overlay package입니다.

이 문서는 Loading API 자체보다, 실제 소비 애플리케이션에서 npm package를 설치하고 로컬 approuter / UI5 build / BTP HTML5 Application Repository 환경에서 정상 동작시키기 위한 설정 방법과 이유를 설명합니다.

패키지 정보

{
  "name": "@bluewardai/ui5-loading",
  "version": "1.0.5",
  "ui5": {
    "namespace": "blueward/ui/loading"
  }
}

UI5 모듈 경로는 다음 namespace를 사용합니다.

blueward.ui.loading
blueward/ui/loading

1. 설치

소비 애플리케이션의 root에서 설치합니다.

npm install @bluewardai/ui5-loading

소비 애플리케이션의 package.json에는 dependencies와 ui5.dependencies를 함께 설정해야 합니다.

{
  "dependencies": {
    "@bluewardai/ui5-loading": "^1.0.5"
  },
  "ui5": {
    "dependencies": [
      "@bluewardai/ui5-loading"
    ]
  }
}

왜 `ui5.dependencies`가 필요한가?

dependencies는 npm이 패키지를 node_modules에 설치하기 위한 설정입니다. 하지만 UI5 Tooling은 npm dependency 전체를 자동으로 UI5 library로 인식하지 않습니다.

ui5.dependencies에 패키지를 등록해야 UI5 Tooling이 해당 패키지의 ui5.yaml을 읽고, blueward.ui.loading을 UI5 library project로 등록합니다. 이 설정이 빠지면 빌드나 로컬 서버에서 다음 경로를 찾지 못할 수 있습니다.

resources/blueward/ui/loading/...

설정 후 아래 명령어로 인식 여부를 확인할 수 있습니다.

npx ui5 tree --flat

정상이라면 출력에 다음 항목이 포함됩니다.

blueward.ui.loading blueward/ui/loading

2. UI5 CLI 버전

이 패키지는 ui5.yaml에서 specVersion: "3.1"을 사용합니다. 따라서 소비 애플리케이션은 UI5 CLI 3.x 이상을 사용해야 합니다.

npm install --save-dev @ui5/cli@^3

UI5 CLI 2.x를 사용하면 빌드 또는 ui5 tree 실행 시 아래와 같은 오류가 발생할 수 있습니다.

Unsupported "specVersion"

이 오류는 패키지 문제가 아니라, 소비 애플리케이션의 UI5 Tooling 버전이 패키지의 ui5.yaml specVersion을 해석하지 못해서 발생합니다.

3. 모듈 import

Controller나 Component에서 일반 UI5 module처럼 import합니다.

sap.ui.define([
  "sap/ui/core/mvc/Controller",
  "blueward/ui/loading/Loading"
], function (Controller, Loading) {
  "use strict";

  return Controller.extend("sample.controller.Main", {
    onLoad: function () {
      return Loading.run(this._loadData(), {
        target: this.getView(),
        text: "Loading..."
      });
    }
  });
});

Loading module은 내부에서 blueward/ui/loading/library를 로드합니다. 여러 화면에서 loading을 공통으로 사용한다면, 앱 시작 시점에 blueward/ui/loading/library를 한 번 import해두는 방식도 사용할 수 있습니다.

4. 기본 사용법

전체 화면 loading:

var handle = Loading.show({
  text: "Loading..."
});

handle.close();

특정 UI5 control 위에 loading:

var handle = Loading.show(this.getView(), {
  text: "Loading data..."
});

handle.close();

Promise 실행 중 자동 loading:

return Loading.run(this._loadData(), {
  target: this.getView(),
  text: "Loading data..."
});

5. CSS / Style 설정

Loading overlay는 패키지 내부의 theme stylesheet를 사용합니다.

blueward/ui/loading/themes/base/library.css

Loading.js가 로드되었더라도 stylesheet가 정상적으로 삽입되지 않으면 overlay가 기대한 형태로 보이지 않을 수 있습니다.

이 문제를 막기 위해 화면 Controller마다 Style을 넣는 방식은 권장하지 않습니다. CSS는 화면 로직이 아니라 애플리케이션 초기화 책임에 가깝기 때문입니다.

소비 애플리케이션에서는 Component.js처럼 앱 시작 시 한 번만 로드되는 module에 blueward/ui/loading/library를 등록하는 방식을 권장합니다.

blueward/ui/loading/library는 내부에서 blueward/ui/loading/Style을 로드하므로, 소비 앱은 Style module을 직접 알 필요가 없습니다.

sap.ui.define([
  "sap/ui/core/UIComponent",
  "blueward/ui/loading/library"
], function (UIComponent) {
  "use strict";

  return UIComponent.extend("sample.Component", {
    metadata: {
      manifest: "json"
    }
  });
});

library module은 UI5 library를 초기화하고, 패키지 CSS가 한 번만 로드되도록 보장합니다.

프로젝트에 별도 bootstrap module이 있다면 Component.js 대신 그곳에 한 번만 import해도 됩니다. 중요한 기준은 “화면별 Controller에 반복 추가하지 않고, 앱 시작 지점에서 library를 한 번만 로드한다”는 것입니다.

`manifest.json`의 `sap.ui5.dependencies.libs`에 넣지 않는 이유

CSS 또는 preload를 강제로 로드하려고 manifest.json에 아래처럼 추가하는 방식은 권장하지 않습니다.

{
  "sap.ui5": {
    "dependencies": {
      "libs": {
        "blueward.ui.loading": {}
      }
    }
  }
}

이 방식은 일부 local approuter / proxy 환경에서 UI5가 custom library preload를 CDN, ABAP app index, 또는 잘못된 runtime 위치에서 찾게 만들 수 있습니다.

Blueward npm package는 SAPUI5 CDN이나 ABAP app index에 존재하는 표준 library가 아니므로, library 초기화는 blueward/ui/loading/library import로 처리하고, 파일 제공은 아래의 resource root / approuter / build 설정으로 처리하는 것이 안전합니다.

6. Resource root 설정

HTML bootstrap에서 blueward.ui.loading namespace가 앱 내부의 resources/blueward/ui/loading을 바라보도록 설정합니다.

애플리케이션 root의 index.html 기준:

<script
  id="sap-ui-bootstrap"
  data-sap-ui-resourceroots='{
    "sample": "./",
    "blueward.ui.loading": "./resources/blueward/ui/loading"
  }'>
</script>

test/flpSandbox.html처럼 한 단계 하위 경로에서 실행되는 파일은 상대 경로가 달라지므로 다음처럼 설정합니다.

<script
  id="sap-ui-bootstrap"
  data-sap-ui-resourceroots='{
    "sample": "../",
    "blueward.ui.loading": "../resources/blueward/ui/loading"
  }'>
</script>

왜 app root 상대 경로를 사용하는가?

approuter에서 애플리케이션이 /myapp/index.html로 서비스되는 경우, 브라우저의 실제 요청은 보통 아래처럼 나갑니다.

/myapp/resources/blueward/ui/loading/Loading.js

따라서 bootstrap에서는 현재 HTML5 앱 root 기준의 상대 경로를 사용하는 편이 로컬 approuter와 BTP HTML5 Repository 양쪽에서 가장 예측 가능합니다.

7. 로컬 approuter 설정

로컬에서 @sap/approuter를 사용하고 xs-app-local.json이 애플리케이션 webapp만 localDir로 바라보는 경우, node_modules에 설치된 Blueward package 파일은 자동으로 서비스되지 않습니다.

예를 들어 아래 catch-all route만 있으면:

{
  "source": "^/myapp/(.*)$",
  "target": "$1",
  "localDir": "../app/webapp"
}

다음 요청은 webapp/resources/...에서 파일을 찾게 됩니다.

/myapp/resources/blueward/ui/loading/Loading.js

하지만 로컬 개발 시 Blueward package의 원본 파일은 보통 아래에 있습니다.

../app/node_modules/@bluewardai/ui5-loading/src/blueward/ui/loading

따라서 xs-app-local.json에서 generic app route보다 먼저 Blueward 전용 route를 추가합니다.

{
  "source": "^/myapp/resources/blueward/ui/loading/(.*)$",
  "target": "$1",
  "localDir": "../app/node_modules/@bluewardai/ui5-loading/src/blueward/ui/loading",
  "cacheControl": "no-cache, no-store, must-revalidate"
},
{
  "source": "^/myapp/(.*)$",
  "target": "$1",
  "localDir": "../app/webapp",
  "cacheControl": "no-cache, no-store, must-revalidate"
}

중요한 점은 Blueward route가 반드시 catch-all route보다 앞에 있어야 한다는 것입니다. 뒤에 있으면 먼저 catch-all route가 요청을 잡아버려 404가 발생할 수 있습니다.

route를 수정한 뒤에는 approuter process를 완전히 종료하고 다시 실행해야 합니다. 실행 중인 approuter는 기존 route table을 메모리에 가지고 있으므로 파일만 수정해도 바로 반영되지 않습니다.

8. UI5 build 설정

배포용 빌드에서는 node_modules의 package source를 runtime에서 직접 읽지 않습니다. 빌드 결과물인 dist 또는 배포 ZIP 안에 Blueward resource가 포함되어 있어야 합니다.

소비 애플리케이션의 ui5.yaml에 dependency include를 추가합니다.

builder:
  settings:
    includeDependency:
      - blueward.ui.loading

빌드 후 아래 파일이 존재해야 합니다.

dist/resources/blueward/ui/loading/library.js
dist/resources/blueward/ui/loading/Loading.js
dist/resources/blueward/ui/loading/themes/base/library.css

9. `ui5 build preload` / CF build 설정

일부 프로젝트는 CF 배포용으로 별도 ui5-deploy.yaml과 ui5 build preload를 사용합니다. 이때 config 파일 구조에 따라 builder.settings를 넣으면 UI5 Tooling이 허용하지 않는 경우가 있습니다.

그 경우 package dependency를 CLI option으로 명시합니다.

{
  "scripts": {
    "build:cf": "ui5 build preload --clean-dest --config ui5-deploy.yaml --include-task=generateCachebusterInfo --include-dependency blueward.ui.loading"
  }
}

Blueward package를 여러 개 사용한다면 --include-dependency를 package별로 반복합니다.

{
  "scripts": {
    "build:cf": "ui5 build preload --clean-dest --config ui5-deploy.yaml --include-task=generateCachebusterInfo --include-dependency blueward.ui.controls --include-dependency blueward.ui.loading"
  }
}

10. `ui5-task-zipper` 사용 시

ui5-task-zipper로 <app-name>.zip을 생성하는 프로젝트는 includeDependencies: true를 설정해야 합니다.

builder:
  customTasks:
    - name: ui5-task-zipper
      afterTask: generateCachebusterInfo
      configuration:
        archiveName: myapp
        includeDependencies: true
        additionalFiles:
          - xs-app.json

이 설정이 없으면 dist/resources/blueward/...에는 파일이 존재하더라도, 최종 ZIP 안에는 dependency resource가 빠질 수 있습니다. 그러면 HTML5 repo mock 또는 BTP HTML5 Application Repository runtime에서 아래 요청이 404가 됩니다.

/myapp/resources/blueward/ui/loading/Loading.js

11. BTP HTML5 Application Repository 배포 확인

BTP HTML5 Application Repository에 배포할 때는 최종 artifact 안에 다음 경로가 포함되어야 합니다.

resources/blueward/ui/loading/

배포 후 브라우저 Network 탭에서 다음 파일들이 200으로 내려오는지 확인합니다.

/myapp/resources/blueward/ui/loading/library.js
/myapp/resources/blueward/ui/loading/Loading.js
/myapp/resources/blueward/ui/loading/themes/base/library.css

12. reuse library resolver / app index 사용 프로젝트 주의

일부 UI5 프로젝트는 manifest.json의 sap.ui5.dependencies.libs를 읽어서 /sap/bc/ui2/app_index/ui5_app_info 같은 ABAP app index API로 reuse library 위치를 찾는 custom script를 사용합니다.

Blueward npm package는 ABAP app index에 등록된 reuse library가 아니므로, 이런 resolver가 있다면 blueward.* namespace는 조회 대상에서 제외해야 합니다.

권장 방식은 다음과 같습니다.

npm package는 package.json의 dependencies와 ui5.dependencies로 관리
runtime 경로는 resourceroots와 approuter route로 관리
build artifact 포함은 includeDependency 또는 --include-dependency로 관리
CSS는 blueward/ui/loading/library 1회 import로 관리

13. 문제 해결

`Loading.js`, `library.js`, `library-preload.js`가 404인 경우

Network 탭에서 실제 Request URL을 먼저 확인합니다.

/myapp/resources/blueward/...가 404라면 local approuter route 또는 배포 artifact 누락 문제일 가능성이 큽니다.
https://ui5.sap.com/resources/blueward/...로 요청된다면 custom library를 SAPUI5 CDN에서 찾고 있는 것입니다. resourceroots 또는 proxy 설정을 확인해야 합니다.
dist/resources/blueward/...에는 있는데 ZIP에는 없다면 ui5-task-zipper의 includeDependencies: true를 확인합니다.

Loading overlay 스타일이 이상한 경우

Loading JavaScript는 로드되었지만 CSS가 로드되지 않은 상태일 수 있습니다.

확인할 것:

blueward/ui/loading/library를 앱 초기 module에서 한 번 import했는지
Network 탭에서 아래 CSS가 200으로 내려오는지

/myapp/resources/blueward/ui/loading/themes/base/library.css

`net::ERR_BLOCKED_BY_ORB`가 발생하는 경우

브라우저가 JavaScript를 기대했는데 실제 응답이 HTML 404 페이지 또는 잘못된 MIME type인 경우 발생할 수 있습니다.

대부분 원인은 다음 중 하나입니다.

approuter catch-all route가 Blueward 요청을 먼저 잡음
Blueward resource route가 없음
resource root가 잘못됨
배포 ZIP에 dependency resource가 빠짐
SAPUI5 CDN으로 custom library를 요청함

설정을 바꿨는데 계속 404인 경우

로컬 approuter process가 이전 route table을 계속 들고 있을 수 있습니다. npm run start로 실행 중인 approuter를 완전히 종료한 뒤 다시 시작합니다.

License

MIT. See LICENSE and NOTICE.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme