Verona Interfaces – Editor

Ein Editor dient der interaktiven onlinegestützten Entwicklung einer Unit. Hierbei stehen die visuelle Erscheinung und die Interaktionselemente im Vordergrund.

Spezifikation

Die Spezifikation der API ist als YML-Datei in der Syntax AsyncAPI ausgeführt. Nach einer Änderung wird über ein Tool eine lesbare Html-Datei erzeugt.

sequenceDiagram
    autonumber
participant HA as Host-Anwendung
    participant VM as Editor (Verona-Modul)
    HA->>VM:Initialisierung
    VM->>HA:voeReadyNotification
    HA->>VM:voeStartCommand
    loop
        VM->>HA:voeDefinitionChangedNotification
    end

1 Initialisierung

Der Host richtet ein <iframe>-Element ein und setzt für das srcdoc-Attribut den kompletten Inhalt des Moduls. Das Modul ist technisch eine Html-Seite, d. h. es wird durch das Laden auch die Ausführung von JavaScript-Code angestoßen, der auf oberster Ebene vorgesehen ist.

2 Ready Notification

Dieser Code sendet als letzten Schritt der eigenen Initialisierung eine Nachricht an den Host, dass das Modul bereit sei für das Start-Kommando. Als Payload wird das Metadaten-Objekt mitgeschickt – hier allerdings als String serialisiert, um nicht bei jeder Änderung der Metadaten-Spezifikation alle Modul-API ändern zu müssen.

3 Start Command

Nachdem der Host die Bereitschaftsmeldung erhalten hat, schickt er die wichtigen Informationen zur Unit und startet so die Beaarbeitung:

• sessionId: Dem Editor wird vom Host mit sessionId eine Kennung mitgeschickt, die der Editor anschließend in jeder Nachricht über die Änderung der Unit-Definition verwenden soll. Damit wird die korrekte Zuordnung der Nachricht bzw. der darin enthaltenen Daten zur Unit unterstützt. Diese ID ist wichtiger, wenn es mehrere Editoren pro Seite beim Host gibt, die gleichzeitig verwaltet werden sollen.
• unitDefinition: Wenn es bereits eine Bearbeitung gab, dann schickt der Host die vorherigen Unit-Definition. Sie beschreibt das Erscheinungsbild der Unit und ggf. die Interaktionselemente. Es kann einfacher Text sein, aber auch kompexe Datenstrukturen – dann serialisiert als String. Dann stellt der Editor für die erste Seite alle Elemente dar, die in der Unit-Definition vorgesehen sind und bereitet die Oberfläche vor.
• unitDefinitionType: Diese Angabe soll dem Editor helfen, Missverständnisse bei der Interpretation der Unit-Definition zu vermeiden. Aus Sicht der Host-Anwendung ist es jedoch wichtiger, Namen und Version des erforderlichen Editors zu kennen. Wenn bekannt ist, dass Editor XY@3.5 für diese Unit-Definition sinnvollerweise benutzt werden sollte, dann muss der Host diesen Editor besorgen. Dann spielt der Typ der Unit-Definition eine untergeordnete Rolle.
• editorConfig:
  • directDownloadUrl: Sollte der Editor während der Laufzeit Code nachladen müssen, kann aus Gründen der Datensicherheit nicht einfach irgendein Server genutzt werden. Dem Editor muss mitgeteilt werden, welche URL dafür zulässig ist. Beispiel: GeoGebra.
  • role: Es kann gewünscht sein, dass nicht für alle Bearbeiter*innen alle Funktionen des Editors gleichermaßen zur Verfügung stehen. Ungeübte fühlen sich eventuell erschlagen von der Fülle der Parameter und nehmen ungünstige Änderungen vor. Die Rolle, die dem Editor hier mitgeteilt wird, variiert die Benutzeroberfläche. Mögliche Werte sind guest, commentator, developer, maintainer, super (abnehmende Beschränkungen).

4 Definition Changed Notification

Sobald eine Bearbeitung der Unit-Definition stattgefunden hat, meldet der Editor diese Änderung. Parameter:

• sessionId: Dem Editor wurde im Start-Kommando eine sessionId eine Kennung mitgeschickt, die der Editor anschließend in jeder Nachricht verwendet. Damit wird die korrekte Zuordnung der Nachricht bzw. der darin enthaltenen Daten zur Unit unterstützt.
• timestamp: Ein String im Standard-Format date-time. Die Nutzung dieser Information ist dem Host überlassen, soll aber vor allem die korrekte Reihenfolge vieler asynchron eintreffenden Nachrichten sicherstellen.
• unitDefinition: Dieser String enthält die neue Unit-Definition sowie deren Typ.
• unitDefinitionType: Diese Angabe soll anderen Anwendungen helfen, Missverständnisse bei der Interpretation der Unit-Definition zu vermeiden.
• dependenciesToPlay, dependenciesToEdit: Diese Einträge beschreiben Abhängigkeiten von externen Bibliotheken oder Diensten für das Editieren oder Abspielen der Unit. Dies kann der Prüfung der Testinhalte auf Vollständigkeit dienen. Wird hier z. B. GeoGebra genannt, kann eine Warnung ausgegeben werden, wenn dieses Softwarepaket nicht verfügbar ist.

Parameter variables

Dass die Unit-Definition nicht dokumentiert ist, hat eine Menge Vorteile, allerdings auch Nachteile. Einige Informationen wären durchaus sinnvoll, anderen Programmierungen zur Verfügung zu stellen. Dazu gehört die Liste aller möglichen Variablen. Dies sind Werte-Tträger, also mit einer ID identifizierbare Quellen von Antwortdaten. Wie genau diese Antwortdaten entstehen oder wo, das ist uninteressant. Nur dass es sie gibt, ist z. B. für die Planung der Kodierung wichtig.

Die Variablenliste wird stets gleichzeitig mit der Unit-Definition geschickt. Sie soll also immer aktuell sein. Die folgenden Parameter werden mitgeliefert:

id, alias, type, format

• Eine Variable braucht eine innerhalb der Unit eindeutige Bezeichnung.
• Ein alias ist eine alternative ID, die durch User vergeben werden kann. Dann kann die ID der Variable nicht mehr geändert werden und bleibt konstant über alle Verarbeitungsschritte und Versionen. Der Alias kann aber nach Bedarf geändert werden. Das IQB hat diese Trennung eingeführt, als sich Umbenennungen von Variablen häuften und jede Umbenennung Inkonsistenzen verursachte (Ableitungen schlugen fehl, Seitenzustände wurden falsch ermittelt).
• Mögliche Werte für Typ:
  • string, integer, number, boolean: Entsprechend gängiger simpler Datentypen
  • attachment: bezeichnet ein erzeugtes Medium, z. B. ein Bild. Im Kern handelt es sich hier um einen String, der aber eine Referenz darstellt und dem Auswertungssystem das Auffinden des zugehörigen Mediums ermöglicht.
  • no-value: Der Editor ist überzeugt, dass diese Variable für die Auswertung keine Rolle spielt. Manchmal ist z. B. die Sichtbarkeit eines Elementes wichtig zu speichern, aber es wird nie ein nützlicher Wert erzeugt.
  • json: Der Wert ist ein stringifiziertes JSON-Objekt. Dies kann bei komplexen Eingabeelementen erforderlich sein, z. B. Text mit eingebetteten Formeln. Diese Antworten werden dann meist manuell kodiert.
  • coded: Hier wird die Antwort bereits durch den Player codiert. Es kann für die Itementwicklung wesentlich angenehmer sein, die richtige bzw. falsche Antwort bereits im Editor zu definieren und nicht erst im Schemer. Der Player schickt dann die Antworten bereits mit der Information code und score und setzt als Antwortstatus CODING_COMPLETE. Die Kodierung wird dann als abgeschlossen angesehen und jede Kodierregel ignoriert.
• Werte für format:
  • text-selection: Ein String, der Daten für eine Textmarkierung enthält
  • image, capture-image, audio: Spezifiziert den Datentyp attachment
  • ggb-file, ggb-variable: Strings mit besonderem Bezug zu GeoGebra
  • non-negative: spezifiziert integer oder number
  • latex, math-ml, math-table: Strings mit besonderem Bezug zu mathematischen Formeln oder Ausdrücken
  • math-text-mix: Gemischtes JSON-Objekt mit Text und Formeln

multiple, nullable

Diese booleschen Werte kennzeichnen, ob die Variable ein Array des beschriebenen Typs und Formats enthält und ob der Wert null möglich ist.

values, valuePositionLabels, valuesComplete

Diese Angaben liefern genauere Informationen über die möglichen Werte der Variablen. Wenn valuesComplete true ist, dann handelt es sich sogar um eine vollständige Liste, und die Kodierung kann automatisch erfolgen.

page

Diese Information verortet die Quelle des Variablenwertes auf einer Seite der Unit.