docs: 📝 Add WebApp-Wrapper

main.tex

@@ -53,7 +53,7 @@
 
 \bigsection[sec:WebApp-Wrapper]{WebApp-Wrapper}
 \include{src/04_WebApp-Wrapper/01_Zielsetzung.tex}
-\include{src/04_WebApp-Wrapper/02_Benutzeroberfläche.tex}
+\include{src/04_WebApp-Wrapper/02_Bibliotheken.tex}
 \include{src/04_WebApp-Wrapper/03_Implementation.tex}
 \include{src/04_WebApp-Wrapper/04_Benutzung.tex}
 

references.bib

@@ -228,3 +228,30 @@ @misc{stackoverflow
   howpublished = {\url{https://stackoverflow.com}},
   note         = {[Online; Abgerufen am 4. September 2023]}
 }
+
+@misc{pico,
+  author       = {{Pico Beitragende}},
+  title        = {Pico CSS},
+  year         = {2023},
+  publisher    = {GitHub},
+  howpublished = {\url{https://github.com/picocss/pico}},
+  note         = {[Online; Abgerufen am 12. September 2023]}
+}
+
+@misc{symbols,
+  author       = {{Google Inc.}},
+  title        = {Material Icons / Material Symbols},
+  year         = {2023},
+  publisher    = {GitHub},
+  howpublished = {\url{https://github.com/google/material-design-icons}},
+  note         = {[Online; Abgerufen am 12. September 2023]}
+}
+
+@misc{noto,
+  author       = {{Google Inc.}},
+  title        = {Noto Sans},
+  year         = {2023},
+  publisher    = {Google Fonts},
+  howpublished = {\url{https://fonts.google.com/noto/specimen/Noto+Sans}},
+  note         = {[Online; Abgerufen am 12. September 2023]}
+}

src/04_WebApp-Wrapper/01_Zielsetzung.tex

@@ -1,9 +1,31 @@
 \subsection{Zielsetzung}
 
-\begin{figure}[H]
-    \centering
-    \includegraphics[width=\textwidth]{assets/04_WebApp-Wrapper/01_Zielsetzung.drawio.pdf}
-\end{figure}
+Das Hauptziel des WebApp-Wrappers ist es, Webentwicklern zu ermöglichen, eine Webseite mit geringem Aufwand in eine Anwendung zu verpacken, die für alle gängigen Desktop- und Mobile"=Plattformen (Windows, Linux, macOS, Android und iOS) kompiliert werden kann.
 
+Um den Funktionsumfang der Anwendung zu erweitern, soll es auch möglich sein, ein Node.js Projekt zu integrieren.
 
-\clearpage
+Der WebApp-Wrapper soll eine einfache Benutzeroberfläche enthalten, um Webentwicklern das Erstellen einer intuitiven Benutzererfahrung in der Anwendung zu erleichtern.
+Die Oberfläche soll folgende Funktionen enthalten:
+
+\begin{itemize}
+  \setlength\itemsep{-0.5em}
+  \item \textbf{Ladebildschirm:}
+  Informiert den Endbenutzer über das Laden der Webseite.
+  \item \textbf{Fehlerbildschirm:}
+  Informiert den Endbenutzer über mögliche Fehler, wenn etwa Serverprobleme vorliegen oder die Internetverbindung fehlt.
+  \item \textbf{Meldungsfenster:}
+  Zeigt Nachrichten an, um den Endbenutzer um eine Eingabe zu bitten oder ihm Informationen zu liefern.
+  \item \textbf{Menüleiste:}
+  Bietet die Möglichkeit zusätzliche Schaltflächen anzuzeigen, die nicht in der Webseite selbst enthalten sind.
+\end{itemize}
+
+Darüber hinaus soll eine \ac{api} bereitgestellt werden, über die die Webseite und das Node.js Projekt miteinander kommunizieren können.
+Um die Anpassung der Anwendung an die individuellen Bedürfnisse zu ermöglichen, soll die \ac{api} auf der Webseite sowie im Node.js Projekt die folgenden Funktionen bieten:
+
+\begin{itemize}
+  \setlength\itemsep{-0.8em}
+  \item Steuern der geladenen Webseite
+  \item Ändern der Hauptfarbe von der Benutzeroberfläche
+  \item Anpassen, Anzeigen und Ausblenden des Meldungsfensters
+  \item Nachträgliches Ändern, Anzeigen und Ausblenden der Menüleiste
+\end{itemize}

src/04_WebApp-Wrapper/02_Bibliotheken.tex

@@ -0,0 +1,27 @@
+\subsection{Verwendete Bibliotheken}
+
+In diesem Abschnitt werden die Bibliotheken vorgestellt, die bei der Entwicklung der Benutzeroberfläche des WebApp-Wrappers verwendet wurden.
+
+\subsubsection{PicoCSS}
+
+PicoCSS ist ein minimales und responsives Designsystem, das in reinem \ac{css} implementiert ist.
+Mit diesem Framework können Webentwickler schnell und einfach responsive Webseiten erstellen.
+Das Framework verwendet ausschließlich \acs{html}"=Elemente und -Attribute, um die Gestaltung von Webseiten zu ermöglichen.
+Dadurch wird der Code sauberer und leichter zu pflegen.
+\cite{pico}
+
+\subsubsection{Material Symbols}
+
+Material Symbols umfasst eine Reihe von Symbolen, die von Google entwickelt wurden.
+Die Symbole haben einen einfachen und minimalistischen Stil, sind in verschiedenen Größen erhältlich, einfach zu verwenden und einfach zu verstehen.
+\cite{symbols}
+
+\subsubsection{Noto Sans}
+
+Noto Sans ist eine von Google entwickelte Schriftart, die von Millionen von Menschen weltweit verwendet wird.
+Die Schrift ist klar und prägnant und in verschiedenen Stärken und -breiten erhältlich.
+Die Schrift unterstützt mehrere Schriftsysteme, darunter Latein, Kyrillisch und Griechisch.
+Latein ist das gängigste Schriftsystem der Welt.
+Kyrillisch ist ein Alphabet, das für verschiedene Sprachen in ganz Eurasien verwendet wird.
+Griechische Symbole werden häufig in wissenschaftlichen Schriften verwendet.
+\cite{noto}

src/04_WebApp-Wrapper/03_Implementation.tex

@@ -1,9 +1,93 @@
 \subsection{Implementation}
 
+Zur Umsetzung des WebApp-Wrappers wurden die beiden Frameworks Capacitor und Electron verwendet.
+Diese beiden Frameworks bieten eine Reihe von Vorteilen, darunter eine einfache Handhabung, eine weite Verbreitung, einfache Erweiterungsmöglichkeiten, die Möglichkeit, Anwendungen mit \ac{html}, \ac{css} und JavaScript zu erstellen und Schlussendlich die Möglichkeit die Anwendung für alle gängigen Desktop- und Mobile"=Plattformen zu kompilieren.
+\cite{capacitor:docs, electron:docs}
+
+Um das Einbinden eines Node.js Projekts zu ermöglichen, wurde das zuvor entwickelte Plugin \hyperref[sec:Capacitor-NodeJS]{Capacitor-NodeJS} verwendet.
+Dieses Plugin ermöglicht die Integration eines Node.js Projekts in eine Capacitor Anwendung.
+Dadurch können weitere Funktionen mit JavaScript in die Anwendung integriert werden, ohne dass Kenntnisse anderer Programmiersprachen nötig sind.
+
+Um das Einblenden und Steuern von externen Webinhalten zu ermöglichen, wurde das zuvor entwickelte Plugin \hyperref[sec:Capacitor-BrowserView]{Capacitor-BrowserView} verwendet.
+Dadurch kann eine externe Webseite in den WebApp-Wrapper integriert werden.
+
 \begin{figure}[H]
-    \centering
-    \includegraphics[width=\textwidth]{assets/04_WebApp-Wrapper/03_Aufbau.drawio.pdf}
+  \centering
+  \includegraphics[width=0.9\textwidth]{assets/04_WebApp-Wrapper/01_Implementation.drawio.pdf}
+  \caption[WebApp-Wrapper / Implementation]{Implementation des WebApp-Wrappers}
+  \label{asset:WebApp-Wrapper:Implementation}
 \end{figure}
 
+\newpage
+
+\subsubsection{Konfiguration}
+
+Die Konfiguration ist ein wichtiger Schritt bei der Verwendung des WebApp-Wrappers.
+Sie ermöglicht es dem Entwickler, die Anwendung an seine Bedürfnisse anzupassen.
+
+Die wichtigste Konfiguration des WebApp-Wrappers ist die \code{appUrl}.
+Dadurch wird festgelegt, welche Webseite in die Anwendung verpackt bzw.\ angezeigt werden soll.
+Aus Sicherheitsgründen wird die Navigation ausschließlich auf die Angegebene Webseite beschränkt, externe Webseiten werden in einem externen Browser geöffnet.
+
+Alle verfügbaren Konfigurationen werden im Kapitel \nameref{sec:WebApp-Wrapper:Benutzung} aufgeführt.
+
+\subsubsection{Benutzeroberfläche}
+
+Die Benutzeroberfläche des WebApp-Wrappers wurde mithilfe des PicoCSS Frameworks gestaltet und besteht aus einer optionalen Menüleiste, einem Ladebildschirm, einem Ladebalken, einem Fehlerbildschirm und einem Meldungsfenster:
+
+Der Ladebildschirm wird zu Beginn angezeigt, bis die Webseite vollständig geladen ist oder ein Fehler auftritt.
+Wenn die Webseite erfolgreich geladen wurde, wird der Ladebildschirm ausgeblendet und ein Fenster mit der geladenen Webseite (auch BrowserView genannt) wird über die Benutzeroberfläche gelegt, damit der Endbenutzer mit der Webseite interagieren kann.
+Bei einem Fehler wird der Ladebildschirm je nach Art des Fehlers durch den entsprechenden Fehlerbildschirm ausgewechselt.
+Bei einer fehlenden Internetverbindung wird ein Benutzer-Offline Bildschirm angezeigt.
+Bei einem Fehler am Server wird ein Webseite-Offline Bildschirm angezeigt.
+
+Wenn die Webseite erfolgreich geladen wurde und der Endbenutzer auf der Webseite weiter navigiert, wird ein Ladebalken angezeigt, um den Benutzer über den weiteren Ladevorgang zu informieren.
+Dazu wird ein Ladebalken auf der Benutzeroberfläche eingeblednet, und die BrowserView wird etwas verkleinert, sonst würde der Ladebalken verdeckt werden.
+Nach einem erfolgreichen Laden wird der Ladebalken ausgeblendet und die BrowserView mit der geladnen Webseite wird wieder vergrößert.
+
+Wenn bei einem weiteren Ladevorgang ein Fehler auftritt, wird die BrowserView vollständig ausgeblendet und der entsprechender Fehlerbildschirm wird angezeigt.
+
+Wenn eine Menüleiste konfiguriert wurde, wird sie ganz oben angezeigt.
+Bei der Berechnung der Größe der BrowserView, muss die Menüleiste mit berücksichtigt werden, da sie sonst von der BrowserView überdeckt werden könnte.
+
+\newpage
+
+Wenn ein Meldungsfenster über die WebApp-Wrapper \ac{api} eingeblednet wird, wird die BrowserView ausgeblendet um das Meldungsfenster nicht zu überdecken.
+Nach dem schließen des Meldungsfensters wird die BrowserView wieder angezeigt, damit der Endbenutzer weiter mit der Webseite agieren kann.
+Entwickler können das Meldungsfenster mit den bereits gewohnten Sprachen \ac{html} und \ac{css} über die WebApp-Wrapper \ac{api} anpassen.
+
+\begin{figure}[H]
+  \centering
+  \includegraphics[width=\textwidth]{assets/04_WebApp-Wrapper/02_Benutzeroberfläche.drawio.pdf}
+  \caption[WebApp-Wrapper / Benutzeroberfläche]{Einfache Illustration der Benutzeroberfläche des WebApp-Wrappers}
+\end{figure}
+
+Da das Capacitor-BrowserView Plugin das Ausblenden einer BrowserView noch nicht unterstützt, wird als Workaround die Höhe und Breite der BrowserView auf 0\,Pixel gesetzt.
+Dies ist vergleichbar mit einem vollständigen Ausblenden.
+
+Wenn der Endbenutzer die Größe des Anwendungsfensters ändert, muss die Größe der BrowserView angepasst werden.
+Dazu wird die Größe der BrowserView bei jeder Änderung der Größe des Anwendungsfensters neu berechnet.
+
+Während der Implementierung wurde festgestellt, dass es zu Problemen kommt, wenn die BrowserView die Benutzeroberfläche vollständig überdeckt.
+Dadurch können Größenänderungen des Anwendungsfensters nicht mehr erfasst und die Größe der BrowserView nicht neu berechnet werden.
+Um dieses Problem zu umgehen, wird um der BrowserView herum allen Seiten ein Pixel freigelassen, damit die Benutzeroberfläche nicht vollständig überdeckt wird.
+
+\newpage
+
+\subsubsection{WebApp-Wrapper API}
+
+Der WebApp-Wrapper stellt eine \ac{api} bereit, um die Kommunikation zwischen der Webseite und dem integrierten Node.js Projekt zu ermöglichen.
+
+Die \ac{api} stellt einen Tunnel zwischen der \ac{api} des Capacitor-BrowserView Plugins und der \ac{api} des Capacitor-NodeJS Plugins dar.
+Wenn eine Nachricht von der Webseite über die Capacitor-BrowserView \ac{api} gesendet wird, empfängt der WebApp-Wrapper diese Nachricht und leitet sie, über die Capacitor-NodeJS \ac{api}, an das Node.js Projekt weiter.
+Das gleiche Prinzip gilt auch in die andere Richtung.
+
+Darüber hinaus stellt der WebApp-Wrapper eine \ac{api} bereit, um Konfiguration dynamisch zu ändern und ein Meldungsfenster ein- und auszublenden.
+Dieser Teil der \ac{api} ist sowohl im Node.js Projekt als auch auf der geladenen Webseite verfügbar.
+
+Um auch im Meldungsfenster bestimmte Aktionen integrieren zu können, wird vom WebApp Wrapper eine simple \ac{api} bereitgestellt um das Meldungsfenster zu schließen oder Nachrichten zur Webseite oder zum Node.js Projekt zu senden.
+Diese \ac{api} Methoden können einer Schaltfläche im Meldungsfenster hinterlegt werden.
+Somit kann beispielsweise eine Schaltfläche im Meldungsfenster angezeigt werden, um das Meldungsfenster wieder zu schließen, oder um eine Nachricht zum Node.js Projekt zu senden, welche weitere Aktionen ausführt.
 
-\clearpage
+Um dem Entwickler zusätzliche Kontrolle über die geladene Webseite zu geben, stellt der WebApp-Wrapper im Node.js Projekt eine \ac{api} bereit, um die Webseite bzw.\ die BrowserView zu steuern.
+Dazu werden \ac{api} Methoden des Capacitor-BrowserView Plugins an das Node.js Projekt weitergeleitet.

src/04_WebApp-Wrapper/04_Benutzung.tex

@@ -1,5 +1,18 @@
 \subsection{Benutzung}
+\label{sec:WebApp-Wrapper:Benutzung}
 
+In diesem Kapitel wird erklärt, wie eine Anwendung mithilfe des WebApp-Wrappers erstellt werden kann.
 
+Die neueste Version sowie die dazugehörige Dokumentation sind auf der GitHub"=Projektseite\footnote{\url{https://github.com/hampoelz/WebApp-Wrapper}} zu finden.
 
+Da der WebApp-Wrapper auf dem Capacitor Framework basiert, ist es hilfreich, die Grundlagen von Capacitor zu kennen.
+
+\input{src/04_WebApp-Wrapper/04_Benutzung/01_ErsteSchritte.tex}
+\clearpage
+\input{src/04_WebApp-Wrapper/04_Benutzung/02_Konfiguration.tex}
+\clearpage
+\input{src/04_WebApp-Wrapper/04_Benutzung/03_APINodeJS.tex}
+\clearpage
+\input{src/04_WebApp-Wrapper/04_Benutzung/04_APIWebseite.tex}
 \clearpage
+\input{src/04_WebApp-Wrapper/04_Benutzung/05_APIMeldungsfenster.tex}

src/04_WebApp-Wrapper/04_Benutzung/01_ErsteSchritte.tex

@@ -0,0 +1,98 @@
+\subsubsection{Erste Schritte}
+
+\paragraph{Projektdateien herunterladen}
+
+Um mit der Erstellung einer neuen Anwendung mithilfe des WebApp-Wrappers zu beginnen, müssen zunächst die Projektdateien heruntergeladen und die Abhängigkeiten installiert werden.
+
+Dieser Schritt ist mit den folgenden Befehlen einfach zu bewerkstelligen:
+
+\begin{minted}[breaklines,breakafter=/]{bash}
+# Lädt alle erforderlichen Dateien in den Ordner "AppProjectDir" herunter
+git clone https://github.com/hampoelz/WebApp-Wrapper.git AppProjectDir
+
+# Wechselt das Arbeitsverzeichnis in den Ordner "AppProjectDir"
+cd AppProjectDir
+
+# Installiert alle Abhängigkeiten des WebApp-Wrappers
+npm install
+\end{minted}
+
+\paragraph{Konfigurationen anpassen}
+
+Bevor die neue Anwendung gestartet werden kann, müssen zunächst die erforderlichen Konfigurationen in der Datei \code{capacitor.config.json} angepasst werden. Die folgenden Konfigurationen sind erforderlich:
+
+\begin{itemize}
+  \setlength\itemsep{-0.5em}
+  \item \textbf{\code{appId}}: Eine eindeutige Anwendungs-ID
+  \item \textbf{\code{appName}}: Der Name der Anwendung
+  \item \textbf{\code{appUrl}}: Die \ac{url} der Webseite, die in der Anwendung angezeigt wird.
+\end{itemize}
+
+Weitere Konfigurationen können im Kapitel \nameref{sec:WebApp-Wrapper:Konfiguration} gefunden werden.
+
+\newpage
+
+\paragraph{Plattformen hinzufügen}
+
+Nachdem die Konfiguration abgeschlossen ist, können Plattformen hinzugefügt werden, auf denen die Anwendung ausgeführt werden soll.
+
+Die folgenden Befehle können verwendet werden, um Plattformen hinzuzufügen:
+
+\begin{minted}{bash}
+# Erzeugt die Projektdateien für die Plattformen
+npm run build
+
+# Fügt der Anwendung Unterstützung für eine Plattform hinzu
+npx cap add <Plattform>
+
+# Synchronisiert die Plattform mit den Projektdateien
+npx cap sync <Plattform>
+\end{minted}
+
+Die verfügbaren Plattformen sind \code{android}, \code{ios} und \code{electron}.
+Die Plattform \enquote{Electron} bezieht sich auf Desktop"=Plattformen, also Windows, Linux und macOS.
+
+Wenn die Konfiguration später geändert wird, müssen die folgenden Befehle erneut ausgeführt werden:
+
+\begin{minted}{bash}
+# Aktualisiert die Projektdateien mit den neuen Konfigurationen
+npm run build
+
+# Synchronisiert die angegebenen Plattform mit den Projektdateien
+npx cap sync <Plattform>
+\end{minted}
+
+\paragraph{Node.js Projekt hinzufügen}
+
+Um zusätzliche Funktionen in die Anwendung zu integrieren, kann ein Node.js Projekt in das Verzeichnis \code{nodejs} hinzugefügt werden.
+Dieses Verzeichnis ist bereits vorkonfiguriert, sodass ein Node.js Projekt einfach integrieren werden kann.
+
+Nach dem Hinzufügen oder Ändern des Node.js Projekts müssen die folgenden Befehle ausgeführt werden, um die Projektdateien zu aktualisieren:
+
+\begin{minted}{bash}
+# Aktualisiert die Projektdateien mit dem Node.js Projekt
+npm run build
+
+# Synchronisiert die Plattform mit den Projektdateien
+npx cap sync <Plattform>
+\end{minted}
+
+\newpage
+
+\paragraph{Anwendung starten}
+
+Um die Anwendung schließlich zu starten, kann der folgende Befehl verwendet werden.
+
+\begin{minted}{bash}
+# Öffnet das Projekt für die angegebene Plattform
+npx cap open <Plattform>
+\end{minted}
+
+Dieser Befehl öffnet das Projekt für die angegebene Plattform in der entsprechenden Entwicklungsumgebung. 
+Bei Android und iOS wird Android Studio bzw.\ Xcode geöffnet, wenn diese auf dem System installiert sind.
+In der Entwicklungsumgebung können weitere Aktionen durchgeführt werden, wie das Testen im Emulator, Debuggen oder Kompilieren.
+
+Alternativ kann das Projekt für eine Plattform auch manuell geöffnet werden. Die entsprechenden Plattform"=Projektdateien befinden sich in den Verzeichnissen \code{android} und \code{ios}.
+
+Bei Electron wird die Anwendung direkt gestartet. Weitere Aktionen können dabei im Plattform"=Projektordner \code{electron} durchgeführt werden.
+

src/04_WebApp-Wrapper/04_Benutzung/02_Konfiguration.tex

@@ -0,0 +1,45 @@
+\subsubsection{Konfiguration}
+\label{sec:WebApp-Wrapper:Konfiguration}
+
+Die folgenden Konfigurationen sind verfügbar:
+
+\begin{configuration}{WebApp-Wrapper / Konfiguration}
+  \code{appId}        & \code[typescript]{string}     & Ein eindeutiger Bezeichner für die Anwendung. Sie wird auch als Bundle-ID in iOS und als Anwendungs-ID in Android bezeichnet. Sie muss in umgekehrter Domänennamenschreibweise angegeben werden, was im Allgemeinen einen Domänennamen darstellen, der dem Unternehmen gehört.\\ \hline
+  \code{appName}      & \code[typescript]{string}     & Der benutzerfreundliche Name der Anwendung. Dies sollte der Name sein, der im AppStore angezeigt wird. \\ \hline
+  \code{appUrl}       & \code[typescript]{string}     & Die Adresse der Webseite, die in der Anwendung angezeigt wird. \\ \hline
+  \code{primaryColor} & \code[typescript]{string}     & Die Hauptfarbe der Benutzeroberfläche. Der Standardwert ist \textcolor[HTML]{BB4747}{\code*{"\#1095c1"}} \\ \hline
+  \code{menuColor}    & \code[typescript]{string}     & Die Hintergrundfarbe der Menüleiste. \\ \hline
+  \code{menu}         & \code[typescript]{MenuItem[]} & Eine Liste von Menüelementen. Jedes angegebene Menüelement wird in der Menüleiste angezeigt. Wenn diese Konfiguration nicht festgelegt wurde, wird keine Menüleiste angezeigt. \\ \hline
+  \code{contactUrl}   & \code[typescript]{string}     & Eine Webseite, unter der ein Fehlerbericht erstellt werden kann, wenn die angegebene Webseite aufgrund eines Serverfehlers nicht geladen werden kann. \\ \hline
+\end{configuration}
+
+\newpage
+
+\textbf{Beispiele}
+
+In \code{capacitor.config.json}:
+
+\begin{minted}{json}
+{
+  "appId": "com.company.app",
+  "appName": "Company App",
+  "appUrl": "https://app.company.com/",
+  "primaryColor": "#1b66c9",
+  "menuColor": "#202124",
+  "menu": [
+    {
+      "id": "test-button",
+      "type": "button",
+      "text": "Hello World"
+    }
+  ],
+  "contactUrl": "",
+  "webDir": "dist"
+}
+\end{minted}
+
+\begin{warning}
+    Die Konfiguration \code{webDir} darf nicht verändert werden.
+    Capacitor verwendet diese Konfiguration, um die Plattformen mit den Projektdateien zu synchronisieren.
+    Wenn Sie diese Konfiguration ändern, kann es zu Problemen bei der Synchronisierung kommen.
+\end{warning}