readme tmp

jsteuer

2019-12-10 5ffcf8a467bdee1a85aba3b5aafd04c2be05f486

readme tmp

 README.md

@@ -22,17 +22,100 @@
    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.