From 17ae81f04074ad5b2fdbb21f221e33e69b425e53 Mon Sep 17 00:00:00 2001
From: jsteuer <jan.steuer.htw@gmail.com>
Date: Wed, 05 Feb 2020 11:36:17 +0100
Subject: [PATCH] better docs, ide-tool-utils as ts, es6 and es5
---
README.md | 93 +++++++++++++++++++++++++++++++++-------------
1 files changed, 67 insertions(+), 26 deletions(-)
diff --git a/README.md b/README.md
index 7559fb7..6ec6185 100644
--- a/README.md
+++ b/README.md
@@ -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
--
Gitblit v1.10.0-SNAPSHOT