| | |
|---|
| | | gestartet wurde, kann die API verwendet werden! (Hinweis: durch nachbilden der API kann |
|---|
| | | eine Nutzung ohne IDE ermöglicht werden, siehe `enableOfflineUsageIfNecessary`) |
|---|
| | | |
|---|
| | | |
|---|
| | | ### Empfohlenes Vorgehen |
|---|
| | | Damit externe Werkzeuge ein einheitliches Verhalten aufweisen, sollte wie folgt vorgegangen werden. |
|---|
| | | |
|---|
| | | Als erstes muss sichergestellt werden, dass die MathCoach IDE API auch verfügbar ist. Dies ist beispielsweise |
|---|
| | | nicht der Fall, wenn das Werkzeug ohne die IDE gestartet wurde (und nicht offline-fähig ist) oder diee IDE (aus |
|---|
| | | welchen Gründen auch immer) nicht einsatzbereit ist. |
|---|
| | | |
|---|
| | | if(typeof MC !== "undefined"){ |
|---|
| | | throw new Error("IDE Lib nicht eingebunden"); // TODO: show error to user |
|---|
| | | } |
|---|
| | | const isReady = await MC.isReady(); |
|---|
| | | if(!isReady){ |
|---|
| | | throw new Error("Die MathCoach-API ist nicht einsatzbereit."); // TODO: show error to user |
|---|
| | | } |
|---|
| | | |
|---|
| | | Von nun an kann die IDE API vollständig genutzt werden. Zunächst sollte die Kontext-Datei (die Datei, |
|---|
| | | mit der das Werkzeug gestartet wurde) geladen werden. |
|---|
| | | |
|---|
| | | Ist der Inhalt der Kontext-Datei leer, wurde das Werkzeug vermutlich zum ersten mal gestartet das Werkzeug: |
|---|
| | | - Sich initialisieren (z.B. mit einem leeren oder beispielhaften internem Datenmodell) |
|---|
| | | - Das interne Datenmodell in die Kontext-Datei schreiben |
|---|
| | | - Die zugehörige Aufgabe generieren. Siehe auch `createExerciseFile` weiter unten. |
|---|
| | | |
|---|
| | | Andernfalls kann das zuvor gespeichertes Datenmodell in den Editor geladen werden. |
|---|
| | | |
|---|
| | | Anschließend sollte die generierten Aufgaben in der Vorschau gestartet werden, sodass der Benutzer besser |
|---|
| | | abschätzen kann, wie sich Änderungen im Werkzeug auf die Aufgabe auswirken. |
|---|
| | | |
|---|
| | | |
|---|
| | | let contextFile = await MC.ide.getContextFile(); // Datei, mit der der Editor gestartet wurde |
|---|
| | | let contextFileContent = await MC.ide.fs.readFile(contextFile); |
|---|
| | | let contextFileIsEmpty = contextFileContent === ""; |
|---|
| | | |
|---|
| | | let exerciseFile = createExerciseFile(contextFile); |
|---|
| | | |
|---|
| | | if(contextFileIsEmpty){ |
|---|
| | | // TODO: init application with new data model (maybe with example contents) |
|---|
| | | // write serialized model to context file, e.g. using JSON.stringify(...) |
|---|
| | | let dataModelAsString = JSON.stringify({/* TODO */}); |
|---|
| | | await MC.ide.fs.writeFile(file, dataModelAsString); |
|---|
| | | // generate exercise |
|---|
| | | let generatedExerciseCode = "startup { print('Hallo Welt!') }"; // TODO |
|---|
| | | await MC.ide.fs.writeFile(exerciseFile, generatedExerciseCode); |
|---|
| | | }else{ |
|---|
| | | // TODO: load data model, e.g. using JSON.parse(contextFileContent) |
|---|
| | | // TODO: (overwrite context file and generated exercise file) |
|---|
| | | // TODO: init application based on your data model |
|---|
| | | } |
|---|
| | | |
|---|
| | | // show preview |
|---|
| | | await MC.ide.navigator.navigateToExercise(exerciseFile); |
|---|
| | | |
|---|
| | | Jedes Werkzeug sollte über eine "Speichern"-Funktion verfügen, mit der der Benutzer: |
|---|
| | | - Das interne Datenmodell in die Kontext-Datei speichert (sodass es später wieder geladen werden kann) |
|---|
| | | - Die zugehörige Aufgabe generiert |
|---|
| | | - Die Vorschau zur generierten Aufgabe navigiert |
|---|
| | | |
|---|
| | | |
|---|
| | | ### Aufgaben-Datei generieren |
|---|
| | | |
|---|
| | | Die generierte Aufgabe soll wie die Kontext-Datei benannt sein, sodass diese vom Benutzer schnell |
|---|
| | | zugeordnet werden können. Beispielsweise soll ein Werkzeug, welches mit der |
|---|
| | | Kontext-Datei `/path/to/myExercise.mcq.json` gestartet wird die Aufgabe `/path/to/myExercise.groovy` |
|---|
| | | erzeugen. |
|---|
| | | |
|---|
| | | /** |
|---|
| | | * Kontext-Datei (z.B. "/path/to/myExercise.mcq.json") auf |
|---|
| | | * Aufgaben-Datei (z.B. "/path/to/myExercise.groovy") abbilden. |
|---|
| | | */ |
|---|
| | | export function createExerciseFile(contextFile: MathCoach.File): MathCoach.File { |
|---|
| | | let file: MathCoach.File = { |
|---|
| | | part: contextFile.part, |
|---|
| | | owner: contextFile.owner, |
|---|
| | | path: contextFile.path.split(".")[0] + ".groovy" |
|---|
| | | }; |
|---|
| | | return file; |
|---|
| | | } |
|---|
| | | |
|---|
| | | |
|---|
| | | |
|---|
| | | ### Beispiele |
|---|
| | | Im Verzeichnis `./examples/` finden sich Beispiele für externe Werkzeuge. |
|---|
| | | |
|---|
| | | ### Hilfunktionen für Werkzeug-Entwickler |
|---|
| | | Dieses Paket beinhaltet zusätzlich Hilfsfunktionen für Werkzeug-Entwickler. Beispielsweise kann |
|---|
| | | ein Werkzeug ohne IDE-Anbindung genutzt werden, indem die API nachgebildet wird - aktuell auf |
|---|
| | | Basis des LocalStorage des Browsers. |
|---|
| | | Basis des LocalStorage des Browsers. Dies ist besonders während der Entwicklung nützlich. |
|---|
| | | |
|---|
| | | import { enableOfflineUsageIfNecessary } from "@mathcoach/ide-api"; |
|---|
| | | let offline: boolean = enableOfflineUsageIfNecessary(); |
|---|
| | | |
|---|
| | | // now use the IDE API |
|---|
| | | |
|---|
| | | |
|---|
| | | ### Kleinere Werkzeuge |
|---|
| | | Für kleiner Werkzeuge bietet es sich an im WWW-Verzeichnis zu entwickeln (z.B. |
|---|
