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).
• 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.