Das SAPUI5 Adaptation Project (auch Fiori Adaptation) ist Teil der On-Stack Developer Extensibility im Rahmen der SAP Clean Core Strategie. Diese Technologie zielt darauf ab, die Benutzeroberfläche und Funktionalitäten von Standard SAP Fiori Apps gemäß den spezifischen Anforderungen des Unternehmens anzupassen und zu erweitern. In dieser Anleitung werden wir diverse Änderungen an einer Standard SAP Fiori App vornehmen.
Möchten Sie mehr über SAPUI5 Adaptation Projects bzw. Fiori Adaptations im Kontext von SAP Clean Core erfahren? Dann besuchen Sie auch unseren Blogbeitrag zu dieser SAP Erweiterungsmethode!
Voraussetzungen
Entwicklungsumgebung: Sie benötigen entweder SAP Business Application Studio Devspace oder Visual Studio Code, in dem die Fiori Tools installiert sind. Die Fiori Tools enthalten das SAPUI5 Adaptation Project Template, welches zur Erweiterung von Standard SAP Fiori Apps verwendet wird. In dieser Anleitung nutzen wir das SAP Business Application Studio.
Backend-System: Sie benötigen ein SAP Backendsystem mit installiertem Fiori-Frontendserver, um dieser Anleitung folgen zu können. Sollten Sie keinen Zugriff haben, können Sie einen Nutzer im SAP Gateway ES5 beantrag. In dieser Anleitung werden wir die Anpassung in der SAP Fiori App „Manage Products“ im ES5 Gateway Demo-System der SAP vornehmen.
Cloud Connector (sofern erforderlich): Sollte Ihr Backend-System On-Premise installiert sein, muss ein Cloud Connector installiert und konfiguriert sein, um eine Kommunikation zwischen SAP BTP und Backend-System zu ermöglichen. Bei S/4HANA Cloud Systemen diese Voraussetzung.
Destination an BTP (Business Technology Platform): Das Backend-System, auf dem die SAP Fiori Apps installiert sind, muss über eine Destination an die SAP Business Technology Platform (BTP) angebunden sein. Die Destination muss korrekt konfiguriert werden, damit Sie von der Entwicklungsumgebung auf installierte SAP Fiori Apps und angebundene OData-Services zugreifen können. Hierfür müssen Sie der Destination die Eigenschaft WebIDEUsage=dev_abap,odata_abap,bsp_execute hinzufügen.
SAPUI5 Adaptation Project anlegen
- Öffnen Sie das SAP Business Application Studio und starten Sie ihren Dev-Space.
- Öffnen Sie die Funktion „New Project from Template“. Hierfür stehen Ihnen die folgenden Varianten zur Verfügung:
- „New Project from Template“ auf der „Get Started“ Seite wählen.
- Über das Hamburger-Menü (☰) „File“ -> „New Project from Template“ wählen.
- Über Funktionstaste F1 öffnet sich eine Command Line. Geben Sie hier „template“ ein und wählen Sie die Option “ SAP Business Application Studio: New Project from Template“.
- Wählen Sie das Template „SAPUI5 Adaptation Project“ aus und bestätigen Sie mit „Start“.
- Geben Sie einen sprechenden Projektnamen im Feld „Project Name“ sowie einen Titel für die Applikation unter „Application Title“ ein. Das Feld Namespace wird mithilfe Ihrer Eingaben automatisch angepasst. Ändern Sie diesen Feldinhalt bitte nicht. Bestätigen Sie mit „Next“.
- Wählen Sie das gewünschte System unter „Select System“ aus. In unserem Falle ist dies „ES5“.
- Wählen Sie die zu erweiternde App unter „Select Application“. Sie können sowohl nach dem Namespace sowie nach dem Titel der Applikation suchen. In unserem Fall „Manage Products“. Bestätigen Sie mit „Finish“.
Screenshot: Projektkonfiguration
Das Projekt wird für Sie angelegt, jedoch nicht automatisch dem Workspace hinzugefügt. Um es dem Workspace hinzuzufügen, klicken Sie im Hamburger-Menü (☰) auf „Files“ -> „Add Folder to Workspace“. Selektieren Sie das neu erstellte Projekt und Bestätigen Sie mit „Ok“.
SAPUI5 Adaptation Project Template : Projektstruktur
SAP Fiori Adaptation Projects haben den folgenden Aufbau:
Besonders relevant sind für uns die Change-Dateien, sowie die Extension-Files in den Ordnern „coding“ und „fragments“. Diese Ordner werden allerdings erst angelegt, sobald sie die ersten Artefakte mithilfe des Graphischen Editors erstellt haben. In folgenden Abschnitt erfahren Sie, wie Sie diese hinzufügen.
Änderungen im Graphischen Editor vornehmen
Um den Graphischen Editor zu öffnen, klicken Sie mit der rechten Maustaste auf den Ordner „webapp“ ihres SAPUI5 Adaptation Project und wählen Sie „Open Adaptation Editor“ aus. Der Graphische Editor öffnet sich in einem neuen Browserfenster. Ggf. müssen Sie hierfür Popups für das Business Application Studio erlauben.
Der Graphische Editor verfügt über mehrere Panels zur Bearbeitung der Oberfläche.
Der Graphische Editor öffnet sich im UI Adaptation Modus. Das bedeutet, mit Klick auf Steuerelemente in der Oberfläche werden diese ausgewählt. Eigenschaften des Steuerelementes können im Panel „Properties“ konfiguriert werden. Zusätzlich können Elemente in der Seite per Drag’n’Drop verschoben werden. Per Rechtsklick auf ein Steuerelement erhalten Sie weitere zum Hinzufügen oder Entfernen von Feldern, Fragment und weiteren Steuerelementen.
Die Auswahl kann außerdem über die Outline erfolgen. Hier werden alle Steuerelemente der Seite in der Aufbauhierarchie angezeigt.
Um Funktionen innerhalb der Applikation ausführen zu können oder zwischen Seiten navigieren zu können, müssen Sie in den Navigation Modus wechseln.
Um Änderungen zu aktivieren, müssen diese gespeichert werden. Betätigen Sie dafür das Disketten-Symbol in der oberen Bildschirmmitte.
Änderungen in der Vorschau nachvollziehen
Zur Überprüfung Ihrer Änderungen können Sie die Vorschau (Application Preview) verwenden. Um die Vorschau zu öffnen, klicken Sie mit der rechten Maustaste auf den Ordner „webapp“ ihres SAPUI5 Adaptation Project und wählen Sie die Option „Preview Application“. Es öffnet sich eine Command Line Abfrage zur Auswahl des Start-Skripts in der oberen Bildschirmmitte. Selektieren Sie den ersten Treffer.
Die Vorschau öffnet sich in einem neuen Browserfenster. Gegebenenfalls müssen Sie hierfür Popups für das Business Application Studio erlauben.
Custom Columns in Listreport einfügen
- Öffnen Sie den Graphischen Editor und navigieren Sie auf die anzupassende Seite.
- Um die Quick Action „Add Custom Table Column“ ausführen zu können, benötigen Sie mindestens eine anzuzeigende Zeile. Sollte die Tabelle aktuell leer sein, aktivieren Sie den Navigation Modus, um die Suche zu starten.
- Wechseln Sie zurück in den UI Adaptation Mode und wählen Sie die Quick Action „Add Custom Table Column“ aus.
- Geben Sie sprechende Namen für die zwei zu erstellenden Fragmente ein. Bestätigen Sie mit „Ok“.
- Speichern Sie die Änderungen.
Die weitere Bearbeitung erfolgt nun im Code Editor. Wechseln Sie zurück in das SAP Business Application Studio und öffnen Sie die neu angelegten Fragmente. Sie finden diese im Order „webapp“ -> „changes“ -> „fragments“ ihres SAPUI5 Adaptation Project. Wie Sie sehen, wurde bereits eine Spalte (Column) und Zelle (Cell) beispielhaft hinzugefügt.
Um die neue Spalte fehlerfrei Nutzen zu können, empfiehlt es sich einen CustomData Datensatz mit dem key p13nData anzulegen. Diese Daten geben der Tabellenspalte innerhalb der SmartTable Informationen zur Zuordnung der Daten.
<customData>
<core:CustomData key="p13nData" id="ZCOLUMNVALUESTOCKp13ndata" value='\{"columnKey": "ValueStock", "columnIndex": 4}'/>
</customData>
Custom Action für Email-Versand in Object Page Header einfügen
- Öffnen Sie den Graphischen Editor und navigieren Sie auf die anzupassende Seite, dann wechseln Sie zurück in den UI Adaptation Mode.
- Klicken Sie mit der rechten Maustaste auf den Bereich der Aktionen im Header der Objektseite.
- Wählen Sie „Add: Fragment“ aus.
- Geben Sie dem Fragment einen sprechenden Namen und bestätigen Sie mit „Ok“.
- Führen Sie die Quick Action „Add Controller to Page“ aus.
- Geben Sie dem Controller einen sprechenden Namen und bestätigen Sie mit „Ok“.
- Speichern Sie die Änderungen.
Die weitere Bearbeitung erfolgt nun im Code Editor. Wechseln Sie zurück in das SAP Business Application Studio und öffnen Sie das neu angelegte Fragment sowie den Controller. Sie finden diese im Order „webapp“ -> „changes“ ihres SAPUI5 Adaptation Project.
Wie Sie sehen, wurde im Fragment bereits Button beispielhaft hinzugefügt. Wir ändern den anzuzeigenden Text und fügen einen Event-Listener für das press-Event hinzu. Um Funktionen aus einer Controller Extension nutzen zu können, nutzen Sie hierfür folgenden Aufruf:
press = ".extension.customer.<project name>.<controller name>.<method>"
Den Pfad .customer.<project name>.<controller name> können Sie aus der Definition des Controllers kopieren. Innerhalb des Controllers wurden ebenfalls Beispielmethoden bereitgestellt. Wir ignorieren diese zunächst und fügen folgende Funktion hinzu:
onSendEmailPress : function (event) {
const productName = event.getSource().getBindingContext().getProperty('ProductName')
const receiverEmail = "[email protected]"
const subject = `Inquiry about ${productName}`
const messageBody = `Hello, I am interested in the product: ${productName}.`
sap.m.URLHelper.triggerEmail(receiverEmail, subject, messageBody)
}
Um auf Daten des angezeigten Produktes zuzugreifen, nutzen wir den Binding Context der Seite. Dieser wird ebenfalls an die Header-Actions (in unserem Falle der Button) vererbt.
Prüfen Sie Ihre Änderungen in der Vorschau.
Trouble Shooting
Aggregation Error bei Starten der Vorschau oder dem Graphischen Editor: Speichern Sie Ihre Änderungen und starten Sie den Devspace neu.
Änderungen in Fragmenten erscheinen nicht im Graphischen Editor: Laden Sie die Seite neu und navigieren Sie erneut an die gewünschte Stelle.
Sie haben Fragen, Beratungsbedarf oder benötigen Hilfe bei Ihrer SAP Fiori App Anpassung? Selbstverständlich stehen wir Ihnen auch jederzeit gerne persönlich zur Verfügung. Unsere Angebote zu Beratung und Schulungen zum Thema SAP Fiori finden Sie auf unserer Website.
