Dokumentation

Appearance

Übungen ​

Von dem Vorhaben Übungen in Aktivitäten oder Lernmodule umzubenennenen wurde vorerst abgesehen 😃

Eine Übung ist ein abstrakter Überbegriff für Lernaktivitäten, die Nutzer auf hermeneus durchführen können, bei denen der Nutzer selbst tätig ist und Daten eingeben muss. Übungen können folgende Funktionalitäten haben:

  • Nutzer gibt Daten ein
  • Eingaben werden ausgewertet
  • Nutzer bekommt Rückmeldung
  • Es kann eine WS- und/oder Grammatikprogression festgelegt werden: Auswahl von WS-Listen, Lerneinheiten, Grammatik, Büchern, Reihen
  • Es gibt eine Reihe weiterer aktivititätenspezifischerer Einstellungen
  • Sie können per Tessera geteilt werden
  • Bestimmte Metriken werden geloggt (Verbrauchte Zeit, erreichte Gravitas, durchführender Nutzer)

Beispiele für Übungen: ​

  • Übungen (Legacy)
    • Bedeutungen zuordnen
    • Activitas
    • Vokabeln lernen
    • Formen bestimmen
    • Formen bilden
  • Ludi Romani
    • LudusCursus
    • LudusSaltus
    • …
  • Weitere Übungen in Entwicklung
    • Irrläufer
    • Verwechslungsgefahr

Architektur im Backend und in der Datenbank ​

Eine Übung wird zugleich in zwei Datenbanktabellen abgebildet:

  1. In einer allgemeinen Tabelle uebungen, die lediglich die allgemeinen Informationen über die Übung enthält (id, name, user_id, uebung_id, uebung_type). In Laravel wird sie durch das Model App\Models\Uebung repräsentiert. Dieser abstrakte Layer dient für allgemeine Datenoperationen, die alle Übungen betreffen, z.B.
  • Übungen abrufen,
  • Zuordnung zu Büchern und Lerneinheiten ...
  1. In einer spezifischen Tabelle, die die spezifischen Konfigurationen der Übung enthält. Diese Tabelle hat das Präfix uebung_ und einen spezifischeren Namen. In Laravel wird sie durch ein eigenes Model repräsentiert, z.B. App\Models\UebungLudusCursus. Dieser Layer wird dann relevant, wenn die Übung tatsächlich aufgerufen oder durchgeführt wird.

Der abstrakte Layer dient also als eine Schnittstelle, die die spezifischen Übungen kapselt und es dem Entwickler ermöglicht, freier in seinem eigenen Model zu arbeiten.

Für externe Funktionalitäten bzw. Services, die den Übungen gemeinsam sind, wie z.B. Zeitmessung oder Metriken können separate und möglichst minimalistische Tabellen, die keinerlei übungsspezifische Informationen enthalten, angelegt werden. Diese sollen das Präfix uebung__ (mit doppeltem Unterstrich) tragen. Beispiel: uebung_metriken

Nomenklatur ​

Eine klare Nomenklatur mit Präfixen und Zuständigkeit ist anzustreben. Beispiele:

  • UebungLudusCursus.php (Basismodel in App\Models\)
  • UebungLudusCursusController.php (HTTP-Controller)
  • UebungLudusCursusRequest.php (Eigenständige Requestklasse, falls nötig)
  • UebungLudusCursusBeliebigeVueKomponente.vue
  • Präfixe verwenden:
    • ludus_cursus, ludus_saltus bei Tabellennamen
    • cfg_ als Präfix für Spalten, die einen Konfigurationswert enthalten
  • Suffixe verwenden:
    • _id als Suffix für Fremdschlüssel
  • NULLABLE in jeder Spalte, wo es möglich ist und ein Default-Verhalten für jede Spalte, in der NULLABLE steht (s.o.)
  • content_data als Spalte mit Übungsinhalt als JSON-Array mit nur einem Hierarchie-Level.

Funktionalität ​

Die Funktionen, die Übungen gemeinsam sind, sollen so weit als möglich so abstrahiert werden, dass sie auch in jede andere beliebige Übungen implementiert werden kann. Am expressivsten hat sich die Arbeit mit Traits erwiesen, die von den entsprechenden Klassen benutzt werden können. Beispiele:

hasZeitmessung

Shareable

Es versteht sich von selbst, dass nicht alle Funktionalitäten in Traits ausgelagert werden können. Alternativen sind Serviceklassen.

Konfigurationswerte ​

Bitte für alle Konfigurationswerte, die in der Datenbank NULLABLE sind, ein Standardverhalten festlegen. Das vermeidet lästige Exceptions, wenn man auf einen Wert zugreifen will, der nicht existiert.