Anwender

Administratoren

Dienstleister

Partner

Einleitung

Im Folgenden beschreiben wir den Ablauf einer Anbindung an eine optiGov-Installation durch das JavaScript-Widget. Dabei nennen wir die Kommune, Stadt, bzw. Betreiber der optiGov-Installation zur Einfachheit “Betreiber” und den Dienstleister, welcher die Anbindung an eine Websiite vornimmt und diese betreut “Dienstleister”.

Ablauf der Anbindung

Im Allgemeinen folgt die Integration des JavaScript-Widgets dem hier aufgeführten Ablauf:

1. Erstellung eines OAuth2.0-Clients durch den Betreiber (s.u.)
2. Abfrage aller benötigten Daten (s.u.) durch den Dienstleister bei dem Betreiber
3. Aufsetzen der Server-Konfiguration durch den Dienstleister
4. JavaScript-Widget und Standard-CSS einbinden
5. Optionale CSS Anpassungen vornehmen

Hinweis: Soll das JavaScript-Widget ohne Authentifizierung angebunden werden (es soll z.B. nur optiGov Meet verwendet werden) können alle Schritte bzgl. OAuth2.0 übersprungen werden.

Weitere Informationen

OAuth2.0 Client

Um optiGov im vollen Funktionsumfang in Ihrer Webseite einbinden zu können, müssen (wie oben bereits beschrieben) die folgenden Vorbereitungen auf Seiten des Betreibers getroffen werden. Die dazu benötigten Funktionen können i.d.R. im Backend von optiGov unter dem Punkt “Administration” bzw. “Verwaltung” gefunden werden.

• Erstellung eines neuen OAuth2.0-Clients mit der für die Einbindung spezifischen Return-URL. Diese Return-URL ergibt sich aus dem Installationsort des Widgets und der gewählten URL der Login-Seite (siehe Javascript) und muss bei der Erstellung des OAuth2.0-Clients bekannt sein.

Benötigte Daten und Informationen

Die folgenden Informationen müssen bei dem Betreiber durch den Dienstleister erfragt werden, da sie für die Anbinung benötigt werden:

• URL der Installation
• ID der Verwaltung
• OAuth2.0-Client-ID des neu angelegten OAuth2.0-Clients
• Adress-O-Mat API-Key für die Kartendarstellung (falls gewünscht)

Serverseitige Einrichtung

Eine einfache (und bewährte) Methode das JavaScript-Widget einzubinden, stellt eine zentrale Datei dar, welche alle Anfragen der verschiedenen URLs entgegen nehmen kann. In dieser Datei wird sich später das JavaScript-Widget befinden, welches anhand der URL erkennt welcher Inhalt dargestellt werden soll.

Für die Einbindung auf Ihrer Webseite empfehlen wir daher eine Ordner-Struktur, ähnlich dem unten gezeigten Beispiel, anzulegen:

/mein-optigov-verzeichnis/
|-- .htaccess
|-- index.html

Hierbei ist das Verzeichnis /mein-optigov-verzeichnis lediglich ein Platzhalter für den Ort der Integration auf Ihrer Website.

Hinweis: Da sich der hier konfigurierte Pfad auf die URL auswirkt unter welcher das Widget erreichbar ist, muss dieser ebenfalls in den URLs der Konfiguration abgeändert werden (s. weiter unten).

Die .htaccess-Datei liefert für alle Anfragen an nicht “physisch” existierende Dateien oder Ordner die index.html zurück, in welcher sich das JavaScript-Widget befindet, ohne eine Umleitung im Browser auszulösen.

.htaccess-Datei

# Redirect all requests for non-existing files to the index.html
RewriteEngine on
RewriteCond %{REQUEST_URI} !^/js/
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.html?url=$1 [QSA,L]

Hinweis: In diesem Beispiel verwenden wir eine .htaccess-Datei. Das o.g. Verhalten lässt sich aber auch unter anderen Serverumgebungen wie z.B. einem NGINX problemlos abbilden.

JavaScript Einbindung

Auf der Seite, welche nun immer durch die Serverkonfiguration aufgerufen wird (in unserem Beispiel die index.html -Datei), kann nun das JavaScript-Widget eingebunden werden.

HTML-Container

Dazu muss zum Einen ein Container auf dieser Seite platziert werden, in welchem das Widget gerendert wird.

<!-- optiGov Widget -->
<div id="app"></div>

JavaScript-Modul

Und zum Anderen muss unterhalb davon (oder nachdem das DOM geladen wurde), das eigentliche Widget integriert werden. Bitte achten Sie dabei darauf die jeweiligen Variablen wie z.B. URLs, IDs, etc. gegen Ihre erfragten und abgesprochenen Werte auszutauschen (siehe weiter oben).

<script type="module">    
import * as optiGov from "https://beispiel.optigov.app/widget/optiGov.mjs"    

// JavaScript-Widget rendern    
optiGov.renderWidget({
    // Referenz auf den <div>-Container
    rootContainer: "#app",
    // Konfiguration
    configuration: {
        // URL der optiGov-Installation
        installation: "https://beispiel.optigov.app",
        // ID der Verwaltung, welche dargestellt werden soll
        verwaltungId: 1,
        oauth: {
            // OAuth2.0-Client-ID für die Authentifizierung (muss im Backend mit der return-URL angelegt werden)
            clientId: 2
        },
        // URLs der jeweiligen Seiten (bitte auf Installationspfad anpassen)
        urls: {
            startseite: "/optigov/",
            dienstleistung: "/optigov/dienstleistung/:id",
            einrichtung: "/optigov/einrichtung/:id",
            mitarbeiter: "/optigov/mitarbeiter/:id",  
            themenfeld: "/optigov/themenfeld/:id",
            alleDienstleistungen: "/optigov/alle-dienstleistungen",
						alleEinrichtungen: "/optigov/alle-einrichtungen",
            alleMitarbeiter: "/optigov/alle-mitarbeiter",
            meinKontoDetails: "/optigov/mein-konto-details",
            meinKontoChats: "/optigov/mein-konto-chats",
            meinKontoChat: "/optigov/mein-konto-chat/:id",
            meinKontoAntraege: "/optigov/mein-konto-antraege",
            meinKontoTermine: "/optigov/mein-konto-termine",
            loginRedirect: "/optigov/login", // dies ist die Seite der return-URL für den OAuth2.0-Client
            antragEingereicht: "/optigov/antrag-eingereicht",
        },
        // Konfiguration externer Services
        services: {
            // optiGov Meet
            meet: {
                enabled: true
            },
            // Adress-O-Mat
            adressOMat: {
                enabled: true,
                key: "YOUR_API_KEY"
            }
        }
    }
})
</script>

Hinweis: Dieses Beispiel ist an die imaginäre Instanz beispiel.optigov.app angebunden und liefert das Widget auf der Website unter dem Pfad /optigov aus.

Weitere Konfigurationen

Dem configuration-Objekt der Funktion optiGov.renderWidget(...) können noch weitere Konfigurationen mitgegeben werden:

Icons

Die auf der Startseite des JavaScript-Widgets dargestellten Icons der Themenfelder können über die icons property überschrieben werden. Dabei können die Werte allen Bezeichnern der FeatherIcons entsprechen:

{  
	"icons": [
		"bold",
		"box",
    "command",
    "cpu",
    "github",
    "message-circle",
    "moon"  
	]
}

Texte

Verschiedene Bezeichnungen unterscheiden sich innerhalb von Verwaltungen. Daher können die Gängigsten mithilfe von Textvariablen abgeändert werden:

{  
	"texts": {    
		"buergerservice": "Bürgerservice",    
		"dienstleistung": "Dienstleistung",    
		"dienstleistungPlural": "Dienstleistungen",    
		"einrichtung": "Einrichtung",    
		"einrichtungPlural": "Einrichtungen",    
		"mitarbeiter": "Mitarbeiter",    
		"mitarbeiterPlural": "Mitarbeiter"  
	}
}

Hooks

In besonderen Fällen wird es von dem Betreiber gewünscht sein vor dem Öffnen eines Formulars eine Anwendung zum Abfragen von Daten darzustellen, welche dann in dem Formular bestimmte Felder vorbefüllen kann. Dies ist über die sogenannten “Hooks” möglich. Anstelle des direkten Aufrufs eines Formulars wird dann von dem JavaScript-Widget zuerst eine durch die Konfiguration definierte Seite aufgerufen, auf welcher zusätzliche Daten z.B. über ein HTML-Formular, Karten-Anwendung, etc. gesammelt werden können. Unterschieden wird dabei anhand der ID des Formulars.

{  
	"hooks": {
    "4": "https://meine-domain.dd/?formularId=:id"
  }
}

Möchte man nun das eigentliche Formular aufrufen, so kann man dies mithilfe der Methode optiGov.oeffneAntrag(...) tun:

// ID des Formulars (z.B. aus dem GET-Parameter der Hook-Seite)
const formularId = 1;

// ID der Dienstleistung (z.B. aus dem GET-Parameter der Hook-Seite)
const formularId = 4;

// Erstelle Antragsanfrageconst 
await optiGov.oeffneAntrag({
    // ID des Formulars
    formularId: formularId,
		// ID der Dienstleistung
    formularId: dienstleistungId,
    // Parameter für den Formular-Server
    parameter: {
        "key": "value"
    },
    // Konfiguration wie in `optiGov.renderWidget(...)`
    configuration: {}
})

Component-Modus

Als Alternative zu dem gesamten Widget, ist es auch möglich lediglich eine unterstützte Komponente zu rendern. Dies kann mithilfe der Funktion optiGov.renderComponent(...) geschehen.

<script type="module">    
import * as optiGov from "https://beispiel.optigov.app/widget/optiGov.mjs"

// Komponente rendern    
optiGov.renderComponent({
    // Referenz auf den <div>-Container
    rootContainer: "#app",
    // Eigenschaften für die Komponente
    properties: {
        mode: "mitarbeiter",
        id: 2
    },
    // Konfiguration
    configuration: {} // siehe JavaScript Einbindung
})
</script>

Hier kann mit der properties-Eigenschaft festgelegt werden, welcher Komponenten-Modus (properties.mode) und optional welcher Eintrag (properties.id) dargestellt werden soll. Untersützte Modi sind:

• dienstleistung für alle Dienstleistungen
• mit id für einen Link zu einer einzelnen Dienstleistung
• einrichtung für alle Einrichtungen
• mit id für einen Link zu einer einzelnen Einrichtung mit Detailinformationen
• mitarbeiter für alle Mitarbeitende
• mit id für einen Link zu einem*r einzelnen Mitarbeiter*in mit Detailinformatione
• themenfeld für alle Themenfelder
• mit id für einen Link zu einem einzelnen Thememfeld mit Darstellung der favorisierten Dienstleistunge
• suche für die Suche mit Auto-Vervollständigung
• meet für die Terminvereinbarung (optiGov Meet)
• mit id für eine einzelne Dienstleistung
• mit einrichtungId für die Filterung und Festlegung auf eine bestimmte Einrichtung
• meet-visitor für die Warteschlangenticketbuchung
• mit schalterIds als Array der IDs der verfügbaren Schalter
• mit einrichtungId für die Filterung und Festlegung auf eine bestimmte Einrichtung

CSS Einbindung und Anpassungen

Das im Standard mitgelieferte CSS kann ganz einfach über ein <link>-Tag auf der Webseite eingebunden werden.

<link rel="stylesheet" href="https://beispiel.optigov.app/widget/style.css"/>

Um den Standard-Style möglichst gut an den Style der Webseite anzubinden, können mit wenigen CSS-Variablen die wichtigsten Farben und Größen geändert und angepasst werden. Diese sollten in einer eigenen CSS-Anweisung unterhalb des <link>-Tags eingebunden werden.

<css>    
:root {        
	--color-border: #ececec;        
	--color-accent: #506DE2;        
	--color-link-active: #ff8a58;        
	--color-background-secondary: #ececec;        
	--color-text-on-accent: #ffffff;        
	--color-icon-background: #ececec;        
	--border-radius: 6px;    
}
</css>

Aufbau

Evtl. gewünschte Anpassungen können über eine eigene CSS-Datei bzw. CSS-Anweisungen direkt auf der eingebundenen Seite vorgenommen werden. Der Aufbau des DOMs sieht dabei wie folgt aus:

Der gesamte Inhalt befindet sich in einem Container mit der Klasse optigov-holder. Innerhalb dieses Containers werden die verschiedenen Inhaltsseiten dargestellt. Diese haben jeweils eine eigene Klasse, sodass Elemente inerhalb dieser seperat angesprochen werden können.

Dazu gehören die folgenden Klassen:

• view-alle-dienstleistungen
• view-alle-einrichtungen
• view-alle-mitarbeiter
• view-antrag-eingereicht
• view-dienstleistung
• view-einrichtung
• view-mitarbeiter
• view-themenfeld
• view-login
• view-mein-konto-antraege
• view-mein-konto-chats
• view-mein-konto-details
• view-mein-konto-termine
• view-startseite

• Einleitung
• Ablauf der Anbindung
• Weitere Informationen
• OAuth2.0 Client
• Benötigte Daten und Informationen
• Serverseitige Einrichtung
• .htaccess-Datei
• JavaScript Einbindung
• HTML-Container
• JavaScript-Modul
• Weitere Konfigurationen
• Icons
• Texte
• Hooks
• Component-Modus
• CSS Einbindung und Anpassungen
• Aufbau