htwkalender-pwa/documentation

= HTWKalender-PWA


== Beschreibung

Die HTWKalender-PWA ist eine Progressive Web App, die es ermöglicht, den Stundenplan der Hochschule für Technik, Wirtschaft und Kultur Leipzig anzuzeigen. Die App wurde im Rahmen des Moduls "Progressive Web Apps" im Studiengang Informationstechnik an der HTWK Leipzig entwickelt. Sie ist als Fork vom Projekt "HTWKalender" entstanden.
Dabei sind spezielle Funktionen für die Offline-Nutzung und die Installation auf mobilen Geräten hinzugekommen.

// Gliederung


== Technologien

Die HTWKalender-PWA wurde mit folgenden Technologien entwickelt:

* Vue.js - Web Framework
* PrimeVue - Component Library
* Vite - Build Tool
* Vite-Plugin-PWA - Plugin für PWA-Funktionalitäten
* TypeScript 

// Gliederung

== Features

Die HTWKalender-PWA bietet folgende Features:

* vite pwa plugin
* [line-through]#push notifications for upcoming events#
* semi offline room finder
* offline calendar ical viewer
* [line-through]#async calendar edit#
* setup development server for pwa deployment
* service worker for caching feed
* popup informations in ical viewer
* popup for "copy to clipborad" is difficult to read
* settings page
* setup default page
* fix shadow in ical viewer
* screenshots with "form_factor" set to "wide" pwa installation

[cols="^2a,a", frame="none"]
|===
| image::media/offline-calendar.png[]
| **Offline Calendar** +
The offline calendar allows you to view the calendar without an internet connection. You can manually update the calendar by clicking the refresh button and share the calendar with others over the share api.

| image::media/room-finder.png[]
| **Room Finder** +
The room finder allows you to search for rooms and view their occupancy. You can also view the occupancy of a room offline.

| image::media/settings.png[]
| **Settings** +
In the settings you can change the theme of the app and view the current version. You can also update the app if a new version is available. There are three different languages available: German, English and Japanese.

|===

* share api for room occupation/calendar
* app version in settings and update notification
* more options in room finder
* offline room finder
* downloadable ical/csv file for room occupation


== Projektstruktur

Für den HTWKalender gibts es als Serverseitige Anwendungen zwei Services die Daten bereitstellen und verarbeiten.
Dabei handelt es sich um einen Datenservice für die Raumbelegung und Veranstaltungen der HTWK Leipzig und einen Service nur
für die Generierung und Bereitstellung von der iCal-Feeds. Im Rahmen des PWA Projekts steht aber das Frontend im Vordergrund, welches die Daten dieser Services verarbeitet und anzeigt.
Dabei wurden bestehende Komponenten aus dem HTWKalender Projekt übernommen und um PWA spezifische Features erweitert. Einen genauen Überblick über die Projektstruktur und die Änderungen sind über den link:https://gitlab.dit.htwk-leipzig.de/htwk-software/htwkalender-pwa.[HTWKalender-PWA Fork] im DIT-Gitlab einsehbar.



== Locale Entwicklung

Für die lokale Entwicklung der HTWKalender-PWA nutzen wir den Vite-Server. Dieser kann mit dem Befehl `npm run dev` gestartet werden.
Aber um Service Worker und PWA Features zu testen, muss die App über HTTPS aufgerufen werden. Zudem werden Daten aus den anderen Services benötigt die auch gestartet werden müssen.
Um diese Anforderungen zu erfüllen, haben wir ein Docker-Compose File erstellt, welches die benötigten Services startet und die HTWKalender-PWA über HTTPS bereitstellt.
Dazu muss das Docker-Compose File mit dem Befehl `docker-compose up` gestartet werden.

== Service Worker

Der Service Worker ist ein zentrales Element einer PWA. Er ermöglicht es, die Anwendung offline verfügbar. Der Service Worker wird beim Start der Anwendung installiert und aktiviert. Er lädt die benötigten Dateien in den Cache und stellt sie offline zur Verfügung. Der Service Worker wird im `public/sw.js` definiert.

[source, javascript]
----
import { precacheAndRoute, cleanupOutdatedCaches } from 'workbox-precaching';
import { clientsClaim } from 'workbox-core';

self.skipWaiting();
clientsClaim();

cleanupOutdatedCaches();

// Precache the files from the manifest
precacheAndRoute(self.__WB_MANIFEST);

// Custom precaching logic for the /api/modules endpoint
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open('api-modules-cache').then((cache) => {
      return fetch('/api/modules')
        .then((response) => {
          if (response.ok) {
            return cache.put('/api/modules', response);
          }
          throw new Error('Failed to fetch /api/modules');
        })
        .catch((error) => {
          console.error('Precaching /api/modules failed:', error);
        });
    })
  );
});
----


== Deployment

Für das Deployment der HTWKalender-PWA haben wir uns für die Nutzung von Gitlab CI/CD entschieden. Dabei wird bei jedem Push in das Gitlab-Repository ein Build- und Deploy-Job ausgeführt. Der Build-Job erstellt ein Docker-Image, welches die HTWKalender-PWA enthält. Der Deploy-Job startet dann ein Docker-Container mit dem erstellten Image. Der Container wird auf einem Server gehostet, der über eine Subdomain erreichbar ist. Die Subdomain wird über einen Reverse-Proxy auf den Docker-Container weitergeleitet.
Eine Laufende Instanz der HTWKalender-PWA ist unter link: https://pwa.htwkalender.de[pwa.htwkalender.de] erreichbar.
Die Konfiguration für das Deployment ist im Gitlab-Repository unter
link:https://gitlab.dit.htwk-leipzig.de/htwk-software/htwkalender-pwa/-/blob/main/.gitlab-ci.yml[.gitlab-ci.yml] zu finden.



== Zukünfitige Features

Folgende Features wurden in der aktuellen Version noch nicht umgesetzt, könnten aber in zukünftigen Versionen hinzugefügt werden:

* push notifications for upcoming events (through firebase/cloud messaging)