Dokumentation

Appearance

How To: Erstellen eines neuen Übungsmoduls ​

1. Einleitung ​

Übungsmodule sind in Hermeneus von bestimmten APIs abhängig und sollten daher bestimmten Vorgaben folgen. Mit diesem Leitfaden sollte das allerdings nicht kompliziert sein.

Ziel ​

Wir erstellen eine Beispielübung mit dem Titel "Vokabeltrainer". Hier soll es allerdings nicht darum gehen, die komplette Übungslogik eines Vokabeltrainers zu implementerieren, sondern nur die Basisstruktur und die notwendigen Konfigurationen. Die Implementierung der Übungslogik muss der Entwickler an den entsprechenden Stellen selbst vornehmen.

Schritte ​

Wir gehen systematisch in folgenden Schritten vor:

  1. Wir machen uns kurz mit dem Modulsystem von Hermeneus vertraut.
  2. Wir erstellen zunächst automatisch per Skript einen Modulordner, der bereits sämtlichen Boilerplate-Code für eine Übung enthält. Anschließend verschaffen wir uns einen Überblick über den Modulordner.
  3. Wir fügen alle notwendigen Informationen in die Konfigurationsdateien config.json und module.json. In diesem Schritt ist bereits etwas Vorausplanung nötig, was uns bei der Konzeption der Übungslogik hilft.
  4. Optional: Wir generieren per Skript eine Migration und eine Factory für die Übung, um die Datenbanktabelle und Test-Objekte nicht manuell erstellen zu müssen.
  5. Wir richten zunächst die Backend-Logik ein: Verwendung von API-Routes für CREATE, READ, UPDATE, DELETE-Operationen. Hier werden auch die Stellen erläutert, wo die Übungslogik implementiert werden kann.
  6. Verknüpfung mit dem Frontend: Die Verwendung der Frontend-Komponenten folgt bestimmten Vorgaben. Hier wird außerdem gezeigt, wie die Verbindung zum Backend hergestellt wird, wie Komponenten verwendet werden und eigene Frontend-Assets integriert werden können.
  7. Auswertung und Bewertung der Übung: Implementierung der Evaluation-Logik für Punktevergabe, Gravitas-Berechnung und Feedback-Generierung.
  8. Troubleshooting und Pitfalls: Häufige Fehlerquellen und deren Lösungen, sowie eine Checkliste für das Deployment.

Inhaltsverzeichnis ​

  1. Einleitung und Grundlagen
  2. Anlegen eines neuen Übungsmoduls und Erklärung des Modulverzeichnisses
  3. Anpassung der module.json und der config.json
  4. Erstellung von Migration und Factory
  5. Einrichtung der Backend-Logik
  6. Anbindung des Frontends
  7. Auswertung und Bewertung der Übung (Evaluation)
  8. Troubleshooting und Pitfalls

1. Einleitung und Grundlagen ​

Ein Übungsmodul ist ein Subtyp eines Moduls in Hermeneus. Übungsmodule werden wie ein generisches Modul behandelt, aber zusätzlich in einer sogenannten UebungenRegistry registriert. Die UebungenRegistry ist eine zentrale API, die alle Informationen zur Verwendung der Übungen im Backend und Frontend zur Verwendung stellt.

1.1 Die UebungenAPI ​

Damit die Entwicklung neuer Übungen für Entwickler mogelijkst unkompliziert erfolgen kann, wurde die UebungenAPI angelegt. Sie fungiert als "Kapsel" um ein spezifisches Übungsmodul und stellt bereits einige Grundfunktionien zur Verfügung, um die sich der Entwickler nicht mehr kümmern muss (z.B. automatische Validierung, Standardmethoden für das Teilen von Übungen, etc...). Gleichzeitig gibt die UebungenAPI klare Standards und Nomenklaturen vor, an die sich der Entwickler halten muss.

1.2 Basis-Model und Spezifisches Übungs-Model ​

Es wird auf eine wichtige Unterscheidung hingewiesen: Wenn ein neues Übungsmodul (in unserem Beispiel das Modul UebungVokabeltrainer) erstellt wird, wird (normalerweise) auch ein spezifisches Übungs-Model unter /modules/Uebungen/UebungVokabeltrainer/app/Models/UebungVokabeltrainer.php erstellt. für dieses Übungs-Model werden die Übungen bzw. Übungs-Objekte in einer entsprechenden Datenbanktabelle gespeichert. Zusätzlich wird für bei der Erstellung jeder spezifischen Übung gleichzeitig eine neue Instanz des Basis-Models (/app/Models/Uebung.php) in der Datenbanktabelle uebungen erstellt. An dem Basis-Model hängt die abstrakte Grundfunktionalität der UebungenAPI.

Das Basis-Model und das spezifische Übungs-Model sind über Fremdschlüssel verknüpft.

Für die Entwicklung einer neuen Übungsform ist nur eine Information wichtig:

Bei der Erstellung einer neuen Übung werden zwei neue Datensätze mit unterschiedlichen IDs erstellt:

  • Eine Instanz des Basis-Models in der Datenbanktabelle uebungen, z.B. mit der ID 231435.
  • Eine Instanz des spezifischen Models, z.B. in der Datenbanktabelle uebung_vokabeltrainer, z.B. mit der ID 3.

Die spezifische Übung kann über das Basis-Model geladen werden:

php
$BasisUebungVokabeltrainer = \App\Models\Uebung::find(231435);
$SpezificUebungVokabeltrainer = $BasisUebungVokabeltrainer->specific_uebung;