Project Shims - NPM-Module mit UI5 verwenden

Haben Sie schon einmal von ‚Shims‘ gehört?

Herkömmlich bezeichnet ein Shim ein dünnes Stück Material, mit dem kleine Lücken oder Zwischenräume zwischen Objekten gefüllt werden. Typischerweise dienen sie dazu, einer bestehenden Konstruktion besseren Halt und Sitz zu geben. In der Tech-Welt bezeichnet ‚Shim‘ Polyfills oder Bibliotheken, die einer bestimmten Software beziehungsweise einem Code helfen, eine neuere Umgebung zu unterstützen.

In diesem Blog wird es etwas technischer, und wir sprechen über ‚Project Shims‘ im Kontext von UI5 Tooling.

Shims in UI5

Wenn Sie UI5 (OpenUI5/SAPUI5) kennen, dann wissen Sie bereits, dass UI5 uns ein leistungsfähiges Entwicklungs-Toolkit für den Bau von Apps an die Hand gibt. Aber es kann nicht alles bereitstellen, und es sollte auch nicht alles neu erfinden, was bereits existiert. Jedes Framework löst dieses Problem über Drittanbieter-Tools. Bekannte Beispiele sind die Bootstrap-Bibliothek für responsive UI, lodash für JS-Utility-Funktionen, d3 für Charts und Diagramme und so weiter. Diese Drittanbieter-Bibliotheken sind Shims, die dem UI5-Framework helfen, bessere Apps zu bauen.

Bis UI5 Tooling ins Spiel kam, war die Nutzung von Drittanbieter-Bibliotheken mit UI5 im Vergleich zu anderen JavaScript-Frameworks nicht einfach. Zu den gängigen Wegen, Drittanbieter-Bibliotheken in UI5 zu nutzen, gehörten:

1. Ein CDN-Skript in der index.html der UI5-Anwendung verwenden.
2. Die Bibliotheksdateien herunterladen und im Projekt laden.

Ein wesentliches Problem dieser Ansätze ist, dass sie uns daran hindern, die weltweit größte Software-Registry und die Standardwahl für JavaScript-Pakete zu nutzen: npm. NPM-Pakete helfen erheblich bei einfacher Installation und einfacher Versionsverwaltung. Dieses Problem wird in UI5 nun mit Hilfe von Project Shims gelöst. 🎉

Eine Project-Shim-Extension kann verwendet werden, um die Projektkonfiguration eines Moduls zu definieren oder zu erweitern. Der wohl verbreitetste Anwendungsfall ist es, einem Drittanbieter-Modul eine UI5-Projektkonfiguration hinzuzufügen, das andernfalls nicht mit dem UI5 Tooling verwendet werden könnte.

Der folgende Teil des Blogs setzt ein grundlegendes Verständnis von ui5-tooling und yarn voraus. Falls nicht vorhanden, arbeiten Sie sich durch die UI5 Tooling Dokumentation und die yarn Dokumentation.

(1) Ein UI5-Beispielprojekt vorbereiten:

Wenn Sie noch kein auf ui5-tooling basierendes Projekt haben, folgen Sie einfach den folgenden Schritten:

1. Klonen oder laden Sie das UI5-Boilerplate-Projekt von ‚https://github.com/integrtr/ui5-boilerplate‘ herunter.
2. Installieren Sie die Projektabhängigkeiten mit yarn install
3. Führen Sie yarn start aus, um den lokalen Entwicklungsserver zu starten. Danach können Sie Ihre App im Standardbrowser unter http://localhost:8080 aufrufen.

Voilà! Unsere ui5-starter-app, gebaut mit dem neuen ui5-tooling, ist fertig!

(2) Erweiterung mit NPM-Paketen

Fügen wir unserem aktuellen Projekt lodash und momentjs hinzu. Führen Sie dazu die folgenden Befehle in Ihrem Terminal aus:

yarn add lodash
yarn add moment

UI5 Tooling verlangt, dass alle Abhängigkeiten im Abschnitt ui5 > dependencies der Package.json gepflegt werden. Fügen wir diese Konfiguration unserer Package.json hinzu. So sollte Ihre finale Package.json aussehen.

Tipp: Sie können Ihre Abhängigkeiten mit dem Befehl ui5 tree im Terminal überprüfen.

Neue Module müssen nun in der Datei ui5.yaml gepflegt werden. Das geschieht über die UI5-Tooling-Extension project-shim. Am Ende Ihrer ui5.yaml sollte der folgende Code stehen. Da wir eine Project Extension hinzufügen, muss der folgende Code durch eine neue Zeile mit 3 Bindestrichen (- – -) abgetrennt werden.

---
specVersion: '2.1'
kind: extension
type: project-shim
metadata:
  name: thirdparty # this can be your project shim name
shims:
  configurations:
    lodash: # name as defined in package.json
      specVersion: '2.1'
      type: module # Use module type
      metadata:
        name: lodash
      resources:
        configuration:
          paths:
            /resources/thirdparty/lodash/: ''  # location where modules are stored
    moment: # name as defined in package.json
      specVersion: '2.1'
      type: module # Use module type
      metadata:
        name: moment
      resources:
        configuration:
          paths:
            /resources/thirdparty/moment/: ''  # location where modules are stored

/resources/thirdparty/lodash ist der Ort innerhalb des dist-Ordners, an dem Ihre Module abgelegt werden. Der Ort innerhalb des Ordners /resources/ kann weiter angepasst werden, analog zu /resources/<custom_folder_path>/. Derselbe Pfad wird in der controller- und component-Datei verwendet, um die Node-Module zu importieren.

Jetzt haben wir unsere NPM-Module, und diese sollten im Projekt importiert werden. Der Import kann in jeder beliebigen JS-Datei erfolgen, etwa in Component- oder Controller-Dateien. Wenn Sie ein Paket global verwenden und es direkt beim Laden der Anwendung benötigen, ist es besser, es in der Component.js zu requiren, andernfalls kann es in jeder Controller-Datei requiret werden.

Nachfolgend eine Beispiel-Controller-Datei, in der wir lodash und momentjs zu Demonstrationszwecken verwenden.

Beim Import müssen Sie denselben Pfad verwenden, der in der Datei ui5.yaml angegeben wurde, allerdings ohne den Teil /resources. Am Ende des Pfades muss der Dateiname der JavaScript-Datei des NPM-Pakets ergänzt werden. Zum Beispiel ist lodash.js die Datei innerhalb des Ordners lodash. Falls Sie beim Dateinamen unsicher sind, können Sie das Projekt jederzeit mit yarn build-all bauen, um die Ordnerstruktur einzusehen und den Dateinamen zu finden.

Das war's! Binden Sie nun Ihre bevorzugten npm packages in Ihre UI5-Projekte ein und nutzen Sie großartige Drittanbieter-Bibliotheken, um Ihre eigenen starken UI5-Anwendungen zu bauen.