mathcoach/mathcoach-ide-api.git

parent: aa512b36 | patch | commit | ignore whitespace

jsteuer

2019-07-06 6f8bd7e98be91c60386f2e2291a41cfc1004c8b0

add example

5 files added

	examples/README.md	6 ●●●●● patch \| view \| raw \| blame \| history
	examples/example-ide/MyEditor/editor.html	29 ●●●●● patch \| view \| raw \| blame \| history
	examples/example-ide/MyEditor/editor.js	68 ●●●●● patch \| view \| raw \| blame \| history
	examples/example-ide/README.md	42 ●●●●● patch \| view \| raw \| blame \| history
	examples/example-ide/code_completion.png	patch \| view \| raw \| blame \| history

 examples/README.md

New file
@@ -0,0 +1,6 @@
# Beispiele
-   `example-ide`: 
    Entwickeln eines externen Werkzeuges in der MathCoach-IDE
-   `example-vscode-advanced`: 
    Entwickeln eines externen Werkzeuges mit VSCode, Typescript und 
    Parcel als Build-System

 examples/example-ide/MyEditor/editor.html

New file
@@ -0,0 +1,29 @@
<html>

<head>
    <title></title>
    <meta content="">
    <style>
    </style>
</head>

<body>
    <h1>Demo Editor!!!</h1>
    <p>
        Der Editor beschreibt die Kontext-Datei (Datei, mit dem der 
        Editor gestartet wurde) beispielhaft. Er kann eine Aufgabe generieren
        und die Vorschau zu der generieren Datei navigieren.
    </p>
    <ul>
        <li>
            <button id="btn_write">Kontext-Datei schreiben</button> 
        </li>
        <li>
            <button id="btn_generateExercise">Aufgabe generieren und anzeigen</button> 
        </li>
    </ul>

    <script src="/mathcoach/ui/ide/api/ide-lib.js"></script>
    <script src="./editor.js"></script>
</body>
</html>

 examples/example-ide/MyEditor/editor.js

New file
@@ -0,0 +1,68 @@
(async function () {  
    const isReady = typeof MC !== "undefined" ? await MC.isReady() : false;
    if(!isReady){
        alert("Die MathCoach-API ist nicht einsatzbereit. Wurde das Werkzeug nicht durch die IDE gestartet?");
        throw new Error("mc api not ready");
    }
    
    const btnWrite = document.getElementById("btn_write");
    const btnGenerateExercise = document.getElementById("btn_generateExercise");
    
    const user = await MC.ide.getUserName(); // Angemeldeter Benutzer
    const contextFile = await MC.ide.getContextFile(); // Datei, mit der der Editor gestartet wurde
    
    /**
     * Internes Datenmodell des Werkzeuges. Die grafische Oberfläche soll an 
     * dieses Datenmodell gebunden sein:
     * - Änderungen in der grafischen Oberfläche ändern das Modell 
     * - Änderungen des Modell aktualisieren die grafische Oberfläche
     */
    let data = { 
        user: user,
        timestamp: new Date().toTimeString()  
    }

    /**
     * Schreibt das Datenmodell in die die Kontext-Datei (Datei, mit der das Werkzeug gestartet wurde). 
     * Diese Datei fungiert somit als reiner Datencontainer.
     */
    async function saveDataModel() { 
        let text = JSON.stringify(data); // convert the data model to string    
        await MC.ide.fs.writeFile(contextFile,text);  // write the model to the file that starts the tool  
    }
    btnWrite.addEventListener("click", saveDataModel);
    
    /**
     * Läd das Datenmodell aus der Kontext-Datei
     */
    // async function restoreDataModel(){ /* ... TODO ... */}
    
    
    /**
     * Generiert aus dem Datenmodell eine MathCoach-Aufgabe
     */
    async function generateExercise() { 
        let text = `
            startup {
                print("""
                    Hallo ${data.user}! Diese Aufgabe wurde 
                    um <b>${data.timestamp}</b> Uhr erstellt.
                """)
            }
        `;
        /**
         * Die generierte Aufgabe soll so heißen, wie die Kontext-Datei.
         * Der Pfad wird also wie folgt umgeformt: "/path/to/myExercise.xxx.yyy" 
         * wird zu "path/to/myExercise.groovy"
         */ 
        let path = contextFile.path.substring(0,contextFile.path.indexOf(".")) + ".groovy" 
        let file = { owner: contextFile.owner, part: contextFile.part, path: path }
        await MC.ide.fs.writeFile(file, text);
        await MC.ide.navigator.navigateToExercise(file)
    }
    btnGenerateExercise.addEventListener("click", generateExercise);

}())




 examples/example-ide/README.md

New file
@@ -0,0 +1,42 @@
# Beispiel: Externes Werkzeug in der MathCoach-IDE entwickeln
Dieses Beispiel zeigt, wie man ein externes Werkzeug innerhalb der MathCoach-IDE
entwickeln kann. Dabei stellt die IDE Autovervollständigung für JavaScript-Dateien,
in denen die MathCoach-API verwendet wird, bereit. 

![Entwickeln eines Werkzeugs in der MathCoach-IDE](code_completion.png)

### Vorteile
-   Einfach (auf die Schnelle etwas ausprobieren)
-   Die MathCoach-IDE stellt Autovervollständigung bereit

### Nachteile
-   Keine Typsicherheit, da JavaScript verwendet wird (hier bringt die 
    Autovervollständigung nicht viel)
-   Für größere und komplexere Werkzeuge eher ungeeignet


## Setup
-   Lade das Verzeichnis `MyEditor` in dein www-Verzeichnis von MathCoach hoch
-   Registriere das Werkzeug bei der IDE. Ergänze dazu die `ide-settings.json` in 
    deinem vfs-Verzeichnis (passe die `entry`-Konfiguration entsprechend an!):

        {
            ...
            "editor.external.definitions": [
                ...
                {
                    "displayName": "MyEditor",
                    "entry": "/mathcoach/www/<YOUR_USER_NAME>/MyEditor/editor.html",
                    "description": "...",
                    "developer": "Max Mustermann",
                    "extension": "demo.json"
                }
                ...
            ],
            ...
        }


-   Lade die IDE neu (Seite neu laden, z.B. mit F5)
-   Im Kontextmenü des Explorers können nun MyEditor-Dateien angelegt und anschließend 
    mit dem MyEditor geöffnet werden.

 examples/example-ide/code_completion.png

New file
			@@ -0,0 +1,6 @@
			# Beispiele
			- `example-ide`:
			Entwickeln eines externen Werkzeuges in der MathCoach-IDE
			- `example-vscode-advanced`:
			Entwickeln eines externen Werkzeuges mit VSCode, Typescript und
			Parcel als Build-System

New file
			@@ -0,0 +1,29 @@
			<html>

			<head>
			<title></title>
			<meta content="">
			<style>
			</style>
			</head>

			<body>
			<h1>Demo Editor!!!</h1>
			<p>
			Der Editor beschreibt die Kontext-Datei (Datei, mit dem der
			Editor gestartet wurde) beispielhaft. Er kann eine Aufgabe generieren
			und die Vorschau zu der generieren Datei navigieren.
			</p>
			<ul>
			<li>
			<button id="btn_write">Kontext-Datei schreiben</button>
			</li>
			<li>
			<button id="btn_generateExercise">Aufgabe generieren und anzeigen</button>
			</li>
			</ul>

			<script src="/mathcoach/ui/ide/api/ide-lib.js"></script>
			<script src="./editor.js"></script>
			</body>
			</html>

New file
			@@ -0,0 +1,68 @@
			(async function () {
			const isReady = typeof MC !== "undefined" ? await MC.isReady() : false;
			if(!isReady){
			alert("Die MathCoach-API ist nicht einsatzbereit. Wurde das Werkzeug nicht durch die IDE gestartet?");
			throw new Error("mc api not ready");
			}

			const btnWrite = document.getElementById("btn_write");
			const btnGenerateExercise = document.getElementById("btn_generateExercise");

			const user = await MC.ide.getUserName(); // Angemeldeter Benutzer
			const contextFile = await MC.ide.getContextFile(); // Datei, mit der der Editor gestartet wurde

			/**
			* Internes Datenmodell des Werkzeuges. Die grafische Oberfläche soll an
			* dieses Datenmodell gebunden sein:
			* - Änderungen in der grafischen Oberfläche ändern das Modell
			* - Änderungen des Modell aktualisieren die grafische Oberfläche
			*/
			let data = {
			user: user,
			timestamp: new Date().toTimeString()
			}

			/**
			* Schreibt das Datenmodell in die die Kontext-Datei (Datei, mit der das Werkzeug gestartet wurde).
			* Diese Datei fungiert somit als reiner Datencontainer.
			*/
			async function saveDataModel() {
			let text = JSON.stringify(data); // convert the data model to string
			await MC.ide.fs.writeFile(contextFile,text); // write the model to the file that starts the tool
			}
			btnWrite.addEventListener("click", saveDataModel);

			/**
			* Läd das Datenmodell aus der Kontext-Datei
			*/
			// async function restoreDataModel(){ /* ... TODO ... */}


			/**
			* Generiert aus dem Datenmodell eine MathCoach-Aufgabe
			*/
			async function generateExercise() {
			let text = `
			startup {
			print("""
			Hallo ${data.user}! Diese Aufgabe wurde
			um <b>${data.timestamp}</b> Uhr erstellt.
			""")
			}
			`;
			/**
			* Die generierte Aufgabe soll so heißen, wie die Kontext-Datei.
			* Der Pfad wird also wie folgt umgeformt: "/path/to/myExercise.xxx.yyy"
			* wird zu "path/to/myExercise.groovy"
			*/
			let path = contextFile.path.substring(0,contextFile.path.indexOf(".")) + ".groovy"
			let file = { owner: contextFile.owner, part: contextFile.part, path: path }
			await MC.ide.fs.writeFile(file, text);
			await MC.ide.navigator.navigateToExercise(file)
			}
			btnGenerateExercise.addEventListener("click", generateExercise);

			}())

New file
			@@ -0,0 +1,42 @@
			# Beispiel: Externes Werkzeug in der MathCoach-IDE entwickeln
			Dieses Beispiel zeigt, wie man ein externes Werkzeug innerhalb der MathCoach-IDE
			entwickeln kann. Dabei stellt die IDE Autovervollständigung für JavaScript-Dateien,
			in denen die MathCoach-API verwendet wird, bereit.

			![Entwickeln eines Werkzeugs in der MathCoach-IDE](code_completion.png)

			### Vorteile
			- Einfach (auf die Schnelle etwas ausprobieren)
			- Die MathCoach-IDE stellt Autovervollständigung bereit

			### Nachteile
			- Keine Typsicherheit, da JavaScript verwendet wird (hier bringt die
			Autovervollständigung nicht viel)
			- Für größere und komplexere Werkzeuge eher ungeeignet


			## Setup
			- Lade das Verzeichnis `MyEditor` in dein www-Verzeichnis von MathCoach hoch
			- Registriere das Werkzeug bei der IDE. Ergänze dazu die `ide-settings.json` in
			deinem vfs-Verzeichnis (passe die `entry`-Konfiguration entsprechend an!):

			{
			...
			"editor.external.definitions": [
			...
			{
			"displayName": "MyEditor",
			"entry": "/mathcoach/www/<YOUR_USER_NAME>/MyEditor/editor.html",
			"description": "...",
			"developer": "Max Mustermann",
			"extension": "demo.json"
			}
			...
			],
			...
			}


			- Lade die IDE neu (Seite neu laden, z.B. mit F5)
			- Im Kontextmenü des Explorers können nun MyEditor-Dateien angelegt und anschließend
			mit dem MyEditor geöffnet werden.