From 5ffcf8a467bdee1a85aba3b5aafd04c2be05f486 Mon Sep 17 00:00:00 2001
From: jsteuer <jan.steuer.htw@gmail.com>
Date: Tue, 10 Dec 2019 14:33:51 +0100
Subject: [PATCH] readme tmp

---
 README.md |   85 ++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 84 insertions(+), 1 deletions(-)

diff --git a/README.md b/README.md
index ecec13f..434a589 100644
--- a/README.md
+++ b/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. 

--
Gitblit v1.10.0