From e394226c64ac86e5c07ba63efad67fc629d72946 Mon Sep 17 00:00:00 2001
From: jsteuer <jan.steuer.htw@gmail.com>
Date: Wed, 18 Dec 2019 07:59:18 +0100
Subject: [PATCH] docs
---
README.md | 37 ++++++++++++++++++++++++++-----------
1 files changed, 26 insertions(+), 11 deletions(-)
diff --git a/README.md b/README.md
index ac691a0..e747eb6 100644
--- a/README.md
+++ b/README.md
@@ -9,8 +9,7 @@
-*Beispielhafte Anwendung: Eine Datei wird angelegt und einem Demo-Editor geöffnet. Dieser
-generiert eine Groovy-Aufgabe*
+*Beispielhafte Anwendung: Eine Datei (`file.demo.json` - auch "Kontext-Datei" genannt) wird angelegt. Diese kann direkt durch das Werkzeug (Demo-Editor) geladen werden. Das Werkzeug kann die Kontext-Datei beschreiben (um zu demonstrieren, dass es ein internes Datenmodell persistent speichern kann). Weiterhin kann das Werkzeug eine Groovy-Aufgabe generieren und die Aufgaben-Vorschau anzeigen lassen.*
@@ -171,6 +170,11 @@
+*Über einen Deklarations-Eintrag in der Datei `ide-settings.json` kann ein Werkzeug (lokal) in
+die IDE integriert werden. Der Benutzer kann über das Kontext-Menü Dateien, die mit dem Werkzeug
+geöffnet werden können, anlegen. Wird im WWW-Teil des Dateisystems entwickelt, bietet die IDE
+grundlegende Unterstütztung beim Editieren von JavaScript-Dateien*
+
### Entwicklung größerer Werkzeuge
Für größere Werkzeuge sollten etablierte Entwicklungswerkzeuge verwendet werden, beispielsweise:
- [npm](https://nodejs.org/en/) um externe Bibliotheken (u.A. dieses Paket) einzubinden
@@ -178,7 +182,7 @@
- [TypeScript](https://www.typescriptlang.org/) zum typsischeren Programmieren (und/oder Dateien zu ES6 oder ES5 konformen JavaScript umzuformen)
- [Git](https://git-scm.com/) zur Versionierung des Quellcodes
- [Visual Studio Code](https://code.visualstudio.com/) als Entwicklungsumgebung
-- Unit Tests
+- Unit und End-To-End Tests
Das "gebündelte" Werkzeug muss nach dem Build-Prozess in das WWW-Verzeichnis kopiert und ebenfalls
lokal in die IDE integriert werden, siehe weiter unten.
@@ -203,20 +207,29 @@
Wie man der Git-Repo URL ansieht, werden Git-Tags verwendet um eine Versionierung
[(Semantic Versioning)](https://semver.org/lang/de/) der API zu erreichen. Lässt man die Versionierung weg,
wird die aktuellste Version verwendet. (Siehe Gitblit um verfügbare Versionen einzusehen)
+
+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
+einbinden (siehe *Typdefinition auch ohne Build-System nutzen*).
#### Typdefinition auch ohne Build-System nutzen
Beim Arbeiten mit Visual Studio Code kann man auch ohne Einsatz weiterer Entwicklungswerkzeuge
-und Build-Systeme von der Typdefinition der IDE API profitieren. Hierzu muss ein spezielles Kommentar
-an den Anfang der JavaScript-Datei platziert werden (Pfad anpassen!):
+und Build-Systeme von der Typdefinition der IDE API profitieren. Hierzu muss ein spezielles
+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"/>
Dies sorgt dafür, dass Visual Studio Code Autovervollständigung samt Dokumentation der
-IDE API anbieten kann. Nachteilig ist, dass die `mathcoach-api.d.ts` dazu heruntergeladen
-werden muss.
+IDE API anbieten kann. Sollte es bei Verwendung von TypeScript notwendig sein, kann man eine
+Datei wie `global.d.ts` anlegen und die Triple-Slash Directive dort einmalig hinterlegen.
#### Zertifikat-Problem beheben
Falls es Probleme mit dem HTW Zertifikat gibt, muss das Zertifikat von Newton ggf. von
@@ -237,11 +250,13 @@
## Werkzeuge in die IDE integrieren
Damit die IDE das Werkzeug integrieren kann, muss eine Werkzeug-Deklaration registriert werden. Zur
Entwicklungszeit kann der Werkzeug-Entwickler dies lokal vornehmen. Anschließend können verknüpfte
-Dateien mit dem Werkzeug geöffnet werden und erstellt werden (siehe Kontext-Menüs im IDE-Explorer).
+Dateien mit dem Werkzeug geöffnet und erstellt werden (siehe Kontext-Menüs im IDE-Explorer).
Eine Freischaltung des Werkzeugs für alle Autoren erfolgt durch einen Administrator.
### Lokal (Nur für den Entwickler des Werkzeugs)
-In der IDE muss eine Werkzeug-Deklaration angelegt werden, dazu muss die Datei `ide-settings.json` editiert werden:
+In der IDE muss eine Werkzeug-Deklaration angelegt werden, dazu muss die Einstellungsdatei `ide-settings.json`
+editiert werden. Damit Änderungen an der Einstellungsdatei wirksam werden, muss die MathCoach IDE neu
+geladen (Seite neu laden) werden.
{
...
@@ -261,10 +276,10 @@
| Schlüssel | Beschreibung | Beispiel |
|---------------|---|---|
| displayName | Der Name des Werkzeugs | `"Fill-In-Blank-Editor"` |
-| entry | Der Einstiegspunkt für das Werkzeugs muss sich auf dem selben Server wie die IDE befinden. | `"/mathcoach/www/YOURNAME/tool.html"` |
+| entry | Der Einstiegspunkt für das Werkzeugs muss sich auf dem selben Server wie die IDE befinden. | `"/mathcoach/www/YOURNAME/fib/tool.html"` |
| description | Eine kurze Beschreibung | |
| developer | Name des Werkzeug-Entwicklers | |
-| extension | Dateien anhand der Datei-Erweiterung mit dem Werkzeug verknüpfen. Hier sollte etwas eindeutiges gewählt werden | `"fib.json"` für Dateien wie `someExercise.fib.json` |
+| extension | Dateien anhand der Datei-Erweiterung mit dem Werkzeug verknüpfen. Hier sollte etwas Eindeutiges gewählt werden | `"fib.json"` für Dateien wie `someExercise.fib.json` |
--
Gitblit v1.10.0