Inhaltsverzeichnis
In diesem Blogbeitrag zum Thema „Adaptation Projects" zeige ich Ihnen, wie Sie bestehende SAP Fiori-Applikationen mit dem SAP Business Application Studio erweitern können.
Was ist überhaupt eine SAP Adaptation?
Einige von Ihnen kennen vielleicht noch die Extension Projects aus der SAP Web IDE, dem Vorgänger des SAP Business Application Studio (im Folgendem mit SAP BAS abgekürzt).
Im Prinzip erfüllen beide Varianten die gleichen Anforderungen:
- Sie müssen eine bestehende SAP Fiori App erweitern, möchten aber sichergehen, dass bestehende Funktionalitäten durch die Erweiterung nicht beschädigt werden?
- Oder Sie müssen beispielsweise eine SAP Fiori Elements App erweitern, die prinzipiell nicht für Änderungen vorgesehen ist?
Dann ist das Adaptation Project Ihr Freund!
Adaptations lassen die originale SAP- oder Freestyle-App unangetastet. Es wird lediglich eine Erweiterung angelegt, mit der Sie die gewünschte App während der Laufzeit in veränderter Form ausführen. Diese Adaptation binden Sie dann beispielsweise über eine neue Kachel ins Launchpad ein. So bleibt die originale App in ihrer ursprünglichen Form erhalten. Mit der Adaptation können Sie die App mit den gewünschten Änderungen ausführen, die über die Adaptation eingebunden werden.
Voraussetzung für ein Adaptation Project ist die aktuelle, in der SAP Cloud Foundry-Umgebung der SAP Business Technology Platform zur Verfügung stehende Cloud IDE des SAP Business Application Studio (BAS) als Entwicklungsumgebung.
Derzeit gibt es keine Unterstützung für die SAP BTP (Neo-Umgebung)-basierte Web IDE oder den Visual Studio Code (VS Code), der für die lokale Entwicklung eingesetzt wird.
Als Voraussetzung für diesen Artikel benötigen Sie Grundkenntnisse in der SAP Fiori-Entwicklung sowie Zugriff auf ein lizenziertes SAP BAS. Sollten Sie bisher noch keine Erfahrung in der Entwicklung mit SAP BAS haben, empfehle ich Ihnen meinen vorherigen Blogartikel.
Erste Schritte
Wenn Sie eine SAP Fiori Freestyle App erweitern möchten, sollte eine Adaptation prinzipiell immer funktionieren.
Möchten Sie eine bestehende SAP Fiori App erweitern, sollten Sie zunächst im SAP Fiori Apps-Katalog schauen, ob und wie die Anwendung erweiterbar ist.
In den meisten Fällen sollte eine Erweiterung mittels Adaptation möglich sein.
Anlegen der Adaptation
Starten Sie nun Ihren Devspace im SAP BAS.
Wählen Sie im Home Screen „New Project from Template“ oder starten Sie alternativ mittels Command-Pallete den Template Wizard bzw. wählen Sie im Dateimenü (die drei Balken links im Menü) New -> Project From Template.
Im nun gestarteten Template Wizard wählen Sie „Adaptation Project" aus und klicken auf „Start".
Neues Adaptation-Projekt anlegen
Zielentwicklungsumgebung auswählen
Im nächsten Schritt wählen Sie Ihre Zielentwicklungsumgebung aus. In der Regel sind SAP ABAP oder SAP Cloud Foundry verfügbar.
Projekteigenschaften definieren
Dann wählen Sie den Projektnamen für Ihre Adaptation aus (in der Regel mit Z-Präfix) sowie den Titel, der später beim Ausführen angezeigt werden soll, und den gewünschten Projekt-Namespace.
Im letzten Schritt wählen Sie zunächst das System aus, auf dem sich die App befindet, die Sie erweitern wollen.
Nun werden alle Apps, die sich auf dem System befinden, aufgelistet.
Hier wählen Sie die App aus, die Sie mittels Adaptation erweitern wollen.
Im nächsten Schritt folgt die SAPUI5-Version, die Sie für die Erweiterung nutzen wollen. In der Regel empfehle ich die letzte als „stable“ gekennzeichnete Version.
Den „Safe Mode“ würde ich zunächst einmal aktiviert lassen.
Sie sind hier in den Erweiterungsmöglichkeiten zwar etwas eingeschränkter, aber dafür ist es unwahrscheinlicher, dass es beim Upgrade auf eine neuere SAPUI5-Version Probleme mit der Adaptation gibt.
Das Deaktivieren würde ich nur empfehlen, wenn Sie Ihre geplante Erweiterung mit aktiviertem „Safe Mode" nicht umsetzen können.
Es ist möglich, bei umfangreichen Änderungen auch später noch den „Safe Mode“ zu deaktivieren.
Nun öffnet sich Ihr frisch angelegtes Adaptation Project im SAP BAS und Sie können mit der Erweiterung beginnen.
Schauen wir uns zunächst einmal die Projektstruktur an:
Struktur des frisch angelegten Adaptation Projekts
Das Ganze erscheint noch etwas leer im Vergleich zu einem regulären SAPUI5-Projekt. Das liegt daran, dass die Adaptation kein eigenständig lauffähiges Projekt ist, sondern nur Teile der Zielapplikation mit unseren gewünschten Änderungen überschreibt. Und eben nur diese Dateien werden auf der Projektebene angezeigt.
Die i18n Datei(en) nutzen wir wie gewohnt, um zusätzlich benötigte Texte und Übersetzungen für die Adaptation zu definieren.
Implementierung von View-Erweiterungen
Versuchen wir nun, der GUI ein neues Element hinzuzufügen.
Beim Adaptation Project müssen wir Erweiterungen des Views mithilfe des Visual Editor ergänzen. Wir legen hier keine neuen Views an oder verändern diese direkt im XML oder JavaScript Code wie bei einem regulären SAPUI5-Projekt.
Um den Visual Editor zu starten, klicken Sie rechts auf die Datei manifest.appdescr_variant.
Im Kontextmenü wählen Sie nun „Open in UI5 Visual Editor“.
Auf der rechten Seite sollte sich im Visual Editor nun eine Preview der App öffnen.
Um Änderungen durchzuführen, wechseln Sie zunächst in den Editier-Modus.
Untersuchen wir zunächst ein bestehendes Element des Views, um den Visual Editor näher kennenzulernen.
Klicken Sie im Editiermodus ein bestehendes Element der GUI an, erscheinen in der rechten Seitenleiste sämtliche Properties des jeweiligen SAPUI5-Elements, die wir beispielsweise im XML-View zuweisen oder ändern können.
Setzen Sie die Property „visible" (Sichtbarkeit) auf „false", könnten Sie zum Beispiel das angewählte Control ausblenden.
Probieren wir als nächstes, der App ein neues SAPUI5-Element hinzuzufügen. Um dem bestehenden View ein neues Element hinzuzufügen, klicken Sie rechts in den Preview-Bereich des Visual Editor, in dem ein neues Control platziert werden soll und wählen „Add Fragment“.
Es erscheint ein neues Pop-up-Fenster:
Dialog-Fragment hinzufügen
Wählen Sie nun eine Aggregation (meist content) und Index (), klicken „Create New…" und vergeben einen sinnvollen Namen für unsere XML-Erweiterung. Nach Bestätigung wird ein neues XML-Fragment angelegt, in dem wir unsere neuen Inhalte definieren können.
Im „webapp"-Ordner wird nun ein neuer Ordner „changes" angelegt, in dem sich wiederum ein weiterer Ordner „fragments" befindet. Hier ist nun eine neue XML-Datei (UI5 Fragment) mit unserem vorher angegebenen Namen zu hinterlegt.
Wählen wir nun diese Datei im Code-Editor aus, um unserer Applikation einen neuen Bereich hinzuzufügen.
Im bereits mittels Kommentare markierten Bereich (Zeile 3) können wir sämtliche SAPUI5-Elemente ergänzen.
Neu angelegtes Fragment im „changes"-Ordner
Hier können Sie Ihre neuen Inhalte definieren.
In meinem Beispiel füge ich der Applikation einen neuen Info-Button hinzu.
Der obige Hinweis (Zeile 1) macht darauf aufmerksam, dass jedem neuen XML-Element eine einzigartige IDs zu vergeben ist - dies ist übrigens Pflicht.
Ansonsten wird die View Erweiterung in der Adaptation nicht angezeigt.
Nach dem Speichern Ihrer Änderungen sollte im Visual Editor ein Hinweis über modifizierte Dateien erscheinen. Wählen Sie hier Reload editor, um das Preview Ihrer Änderungen zu begutachten, sofern die Syntax in eurem neuen XML-Fragment korrekt ist.
Hinweis auf Änderungen im Visual Editor
Erweitern der Logik mithilfe von Controller Extensions
Nun zeige ich Ihnen, wie Sie die Logik bestehender Apps mittels Controller Extension erweitern können.
Das Ganze funktioniert ähnlich wie bei der View Extension.
Klicken Sie im Visual Editor (im Editiermodus) rechts auf den Bereich im View, den wir mittels Controller erweitern wollen.
Nun wählen wir dieses Mal die Option „Extend with Controller“ und geben einen neuen Namen für unseren Controller an. Die Dateiendung controller.js wird automatisch ergänzt.
Neuen Controller anlegen
Controller-Namen angeben
Im „changes"-Ordner wird nun ein neuer Ordner „controller" angelegt, in dem sich unser neuer SAPUI5 Controller mit dem angegebenen Namen befindet.
Dieser ist automatisch mit einer Menge auskommentierter Codes versehen.
Wichtig für uns sind die Funktionen „override" und "templateBaseExtension", die wiederum mittels Controller Extension den Controller der originalen App erweitern.
Controller-Extension minimaler Aufbau
Ich möchte in der Controller-Erweiterung auf Klick eine sap.m.MessageBox mit zusätzlichen Informationen darstellen.
Die entsprechende Funktion onInfoButtonPress habe ich bereits dem neuen Button im XML-View zugewiesen.
Definieren wir im Ordner i18n zunächst einen Text, der auf Klick des Buttons ausgegeben werden soll.
Adaptation: neuen i18n-Text ergänzen
Als nächstes geben wir im sap.ui.define der Controller Extension noch den Namespace für die MessageBox mit:
MessageBox definieren
Innerhalb der Aggregation override->templateBaseExtension können wir bestehende Funktionen der Original-App überdefinieren oder neue Funktionen anlegen.
Wollen wir Lifecycle-Methoden der App wie beispielsweise onAfterRendering redefinieren, muss dies oberhalb der override-Aggregation geschehen.
Beispiel: Überdefinieren von SAPUI5 Lifecycle-Funktionen
Allerdings möchte ich in diesem Beispiel meinem Button eine komplett neue Funktion zuweisen.
Diese definiere ich innerhalb der Aggregation templateBaseExtension.
Neue Funktion in „Controller Extension definieren"
Nach dem Speichern und erneuten Laden der App im Visual Editor sollte die neue Funktionalität nun bereits testbar sein.
Ich hoffe, ich konnte Ihnen damit einen guten Einblick in die Möglichkeiten von SAP Fiori Adaptation Projects gewähren.
