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).
  • Ein Typ kann sein: string, integer, number, boolean, attachment – letzteres 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.
  • 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
Subject to change

Die Erprobung von type kann als erfolgreich angesehen werden, bei den format-Optionen wird es noch Bewegung geben. Hier sind mitunter Ideen eingebracht, deren Nützlichkeit sich erst zeigen muss.

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.