Verona Interfaces – Schemer

Ein Schemer dient der interaktiven onlinegestützten Entwicklung eines Kodierschemas. Dies ist eine Sammlung von Vorschriften, wie die Variablenwerte – automatisch oder manuell – kodiert werden sollen. Es können auch neue Variablen als Ableitung vorhandener gebildet werden.

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 Schemer (Verona Modul)
    HA->>VM:Initialisierung
    VM->>HA:vosReadyNotification
    HA->>VM:vosStartCommand
    loop
        VM->>HA:vosSchemeChangedNotification
    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

Parameter variables

Nachdem der Host die Bereitschaftsmeldung erhalten hat, schickt er die Variablenliste: Parameter variables – so, wie der Editor diese Liste erzeugt hat. Nur auf Grundlage der Variablenliste kann ein Schemer arbeiten, denn es handelt sich bei einem Kodierschema ja um die Verarbeitung von Variablenwerten. Der Schemer initialisiert entsprechend die UI.

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.

Weitere Parameter

  • sessionId: Dem Schemer wird eine Kennung mitgeschickt, die der Schemer anschließend in jeder Nachricht zur Änderung des Kodierschemas verwenden soll. Damit wird die korrekte Zuordnung der Nachricht bzw. der darin enthaltenen Daten zur Unit unterstützt.
  • Soweit vorhanden kann ein Kodierschema codingScheme geschickt werden, damit daran weitergearbeitet wird.
  • codingSchemeType: Sollte es Varianten oder Versionen von Kodierschemata geben, kann dies hier dem Schemer mitgeteilt werden. Alternativ (oder parallel) kann natürlich diese Information als Teil der Datenstruktur des Kodierschemas übergeben werden.
  • schemerConfig –> directDownloadUrl: Sollte der Schemer während der Laufzeit Code nachladen müssen, kann aus Gründen der Datensicherheit nicht einfach irgendein Server genutzt werden. Dem Schemer muss mitgeteilt werden, welche URL dafür zulässig ist.

4 Scheme Changed Notification

Sobald eine Bearbeitung des Kodierschemas stattgefunden hat, meldet der Schemer diese Änderung. Parameter:

  • sessionId: Die Kennung aus dem Start-Kommando, um die korrekte Zuordnung der Nachricht bzw. der darin enthaltenen Daten zur Unit zu unterstützen.
  • 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 eintreffender Nachrichten sicherstellen.
  • codingScheme: Das neue vollständige Kodierschema, serialisiert als String.
  • codingSchemeType: Spezifizierung des Datenformates, wenn gewünscht.
  • dependenciesToCode: Abhängigkeiten von externen Bibliotheken oder Diensten für das Kodieren der Antworten der Unit.