mathcoach/mathcoach-ide-api.git

			@@ -1,5 +1,5 @@

			# MathCoach IDE API <small>`Version 2.0.1`</small>
			# MathCoach IDE API <small>`Version 3.0.0`</small>

			In diesem Paket ([Das Gitblit Repository findet sich hier](https://newton.htwsaar.de/gitblit/summary/mathcoach!mathcoach-ide-api.git))
			ist die öffentliche Schnittstelle zur MathCoach Entwicklungsumgebung (IDE) definiert. Mithilfe
			@@ -16,12 +16,12 @@
			## Idee
			Grundlegende Idee ist, dass ein externes Werkzeug nahtlos in die MathCoach IDE integriert werden
			kann. Bestimmte Dateien werden anhand ihrer Dateiendung mit dem Werkzeug verknüpft, sodass der
			Benutzer das passende Werkzeug durch einen einfache Klick im Dateie-Explorer starten kann. Diese
			Datei wird im folgenden Kontext-Datei genannt und soll dazu dienen das interene Datenmodell (also
			Benutzer das passende Werkzeug durch einen einfache Klick im Datei-Explorer starten kann. Diese
			Datei wird im folgenden Kontext-Datei genannt und soll dazu dienen, das interene Datenmodell (also
			alle Informationen, die der Benutzer im Werkzeug angibt) zu speichern. Das Werkzeug soll das gespeicherte
			Datenmodell zu einem späteren Zeitpunkt wieder laden können.

			Ein Werkzeug kann beispielsweise MathCoach-Aufgabe (Groovy-Datei) generieren. Weitere Funktionalitäten
			Ein Werkzeug kann beispielsweise MathCoach-Aufgaben (Groovy-Datei) generieren. Weitere Funktionalitäten
			der IDE - beispielsweise das Starten der generierten Aufgabe in der Aufgaben-Vorschau der IDE - sind
			ebenfalls für den Werkzeugentwickler verfügbar.

			@@ -40,7 +40,7 @@
			auf `HTML`, `JavaScript` und `CSS` gesetzt werden. Außerdem muss das Werkzeug unter
			der Domain des jeweiligen MathCoach-Servers erreichbar sein. Zur Entwicklungszeit legt man das Werkzeug
			dazu im www-Verzeichnis ab. Die von der IDE bereitgestellte `ide-lib.js` Bibliothek
			muss eingebunden werden.
			muss eingebunden werden.

			<script src="/mathcoach/ui/ide/ide-lib.js"/>

			@@ -94,7 +94,7 @@
			- Sich initialisieren. Es ist sinnvoll, dass das Werkzeug mit einem beispielhaften
			Datenmodell inititalisiert wird.
			- Das interne Datenmodell in die Kontext-Datei schreiben
			- Die zugehörige Aufgabe generieren. Siehe auch `contextFileToExerciseFile` weiter unten.
			- Die zugehörige Aufgabe generieren. Siehe auch `contextFileToExerciseFile` in der [Dokumentation der Hilfsfunktionen](./modules/helpers.html).

			Andernfalls kann das zuvor gespeichertes Datenmodell aus der Kontext-Datei in den
			Editor geladen werden. Anschließend sollte die generierten Aufgaben in der Vorschau gestartet werden, sodass der
			@@ -130,32 +130,73 @@



			### Hilfsunktionen für Werkzeug-Entwickler
			### Hilfsunktionen für Werkzeug-Entwickler (IDE-Tool-Utils)

			[Dokumentation der Hilfsfunktionen](./modules/helpers.html)

			Dieses Paket beinhaltet zusätzlich Hilfsfunktionen für Werkzeug-Entwickler. Diese sind aktuell
			in `TypeScript` implementiert und können bei Bedarf auch zukünftig als ES6-JavaScript
			bereitgestellt werden. Zum Einbinden der Funktionen wird demzufolge ein Build-System
			vorausgesetzt. Keine der Hilfsfunktionen wird durch die `ide-lib.js` ausgeliefert!

			Beispielsweise werden diese wie folgt eingebunden und genutzt:

			import { Helpers } from "@mathcoach/ide-api";
			Helpers.enableOfflineUsageIfNecessary()

			Dieses Paket beinhaltet zusätzlich Hilfsfunktionen (auch IDE-Tool-Utils genannt) für
			Werkzeug-Entwickler. Diese sind aktuell in `TypeScript` implementiert, liegen jedoch
			auch als ES6-JavaScript und Standalone-Bibliothek zur direkten Verwendung vor. Keine der
			Hilfsfunktionen wird durch die `ide-lib.js` ausgeliefert!

			> Hinweis: Hilfunktionen ohne Build-System bereitzustellen gestaltet sich schwierig und
			> bringt große Nachteile mit sich:
			> - Als reine JavaScript-Datei - platziert auf einem Server - ist die die
			> Offline-Fähigkeit (siehe `Helpers.enableOfflineUsageIfNecessary()`) von Werkzeugen nicht
			> gewährleistet.
			> gewährleistet, da eine Internetverbindung zum Zugriff notwendig ist.
			> - Werden Dateien oder Code-Ausschnitte von Hand kopiert, muss der Werkzeug-Entwickler sich
			> um das Aktualisieren kümmern.
			>
			> Ein möglicher Kompromiss wäre die Hilsfunktionen als reine JavaScript-Datei (ES5 oder ES6)
			> bereitzustellen und eine Kopie mit dem Werkezug auszuliefern. Der aktuelle Ansatz bettet
			> Hilfsfunktionen durch den Build-Prozess in das Werkzeug ein.
			> Als Kompromiss werden die Hilsfunktionen als reine JavaScript-Datei (ES5 oder ES6)
			> bereitgestellt, sodass diese auch ohne TypeScript nutzbar sind.

			Die IDE-Tool-Utils können wie folgt genutzt werden

			#### Build-System mit TypeScript (empfohlen)

			Das Paket `@mathcaoch/ide-api` muss als npm-Abhängikeit in der `package.json` des Werkzeugs
			angegeben werden. Fortan können die in TypeScript implementierten Hilfsfunktionen - aber
			auch die Schnittstellen der IDE-API - komfortabel verwendet werden. Eine bestmögliche Typsicherheit ist
			gegeben.

			import { Helpers, MathCoach } from "@mathcoach/ide-api";
			Helpers.enableOfflineUsageIfNecessary()
			...
			const file:MathCoach.File = await MC.ide.getContextFile()


			#### Build-System ES6+ JavaScript

			Das Paket `@mathcaoch/ide-api` muss als npm-Abhängikeit in der `package.json` des Werkzeugs
			angegeben werden. Fortan können die in ES6 JavaScript vorliegenden Hilfsfunktionen
			verwendet werden. Die Entwicklungsumgebung sollte grundlegende Hilfen (Autovervollständigung und eingebettete Dokumentation) anbieten.

			import { Helpers } from "@mathcoach/ide-api/dist/es6"
			Helpers.enableOfflineUsageIfNecessary();
			...
			const file = await MC.ide.getContextFile();


			#### Standalone

			Die Hilfsfunktionen liegen als eigenständige Bibliothek vor ( siehe
			`./dist/lib/mathcoach-ide-tool-utils.js`). Diese muss händisch kopiert, in das Werkzeug
			eingebunden und mit ihm ausgeliefert werden. Über die globale Variable `MC_IDE_TOOL_UTILS`
			können die Hilfsfunktionen angesprochen werden. Die verwendete Entwicklungsumgebung kann
			in der Regel nur wenig Unterstütztung anbieten (siehe auch Typdefinition auch ohne Build-System nutzen).

			// tool.html
			<script src="/mathcoach/ui/ide/ide-lib.js"/>
			<script src="mathcoach-ide-tool-utils.js"/>
			<script src="tool.js"/>

			// tool.js
			const { Helpers } = MC_IDE_TOOL_UTILS;
			Helpers.enableOfflineUsageIfNecessary();
			...
			const file = await MC.ide.getContextFile();




			### Beispiele
			@@ -203,14 +244,14 @@
			...
			}

			Der Git-Repo URL kann man eine Versionsnummer anhängen (z.B. `".../mathcoach/mathcoach-ide-api.git#2.0.0"`
			für Version `2.0.0`), sodass die API falls notwendig versioniert [(Semantic Versioning)](https://semver.org/lang/de/) w
			erden kann.
			Der Git-Repo URL kann man eine Versionsnummer anhängen (z.B. `".../mathcoach/mathcoach-ide-api.git#3.0.0"`
			für Version `3.0.0`), sodass die API, falls notwendig, versioniert [(Semantic Versioning)](https://semver.org/lang/de/) werden kann. Verfügbare Versionen sind Git-Tags und können in der Weboberfläche des Git-Repositories
			oder über die Konsole (`git tag --list`) eingesehen werden.

			Nun können Hilfsfunktionen (in TypeScript) wie folgt eingebunden werden.

			import { Helpers } from "@mathcoach/ide-api";


			Die Typedefinition sollte automatisch verfügbar sein, sodass der Umgang mit der
			IDE API (Einstiegspunkt ist die globale Variable `MC`) durch eine Entwicklungsumgebung
			wie Visual Studio Code unterstützt wird. Falls nicht, muss man die Typdefinition händisch
			@@ -224,7 +265,7 @@
			Kommentar (Triple-Slash Directive) an den Anfang der JavaScript-Datei platziert
			werden (`path` falls nötig anpassen):

			/// <reference path="../node_modules/@mathcoach/ide-api/mathcoach-api.d.ts"/>
			/// <reference path="../node_modules/@mathcoach/ide-api/dist/es6/MathCoach.d.ts"/>

			Dies sorgt dafür, dass Visual Studio Code Autovervollständigung samt Dokumentation der
			IDE API anbieten kann. Sollte es bei Verwendung von TypeScript notwendig sein, kann man eine