README.md

@@ -8,8 +8,8 @@
können. Darüber hinaus werden als Ergänzung einige Hilfsfunktionen zum Bau von Werkzeugen angeboten.

![Demo](media/usage_author.gif)
*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.*



@@ -18,11 +18,12 @@
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
alle Informationen, die der Benutzer im Editor angibt) zu speichern. Das gespeicherte Datenmodell kann 
zu einem späteren Zeitpunkt wieder geladen werden. Weiterhin kann das Werkzeug aus dem internen 
Datenmodell eine MathCoach-Aufgabe (Groovy-Datei) generieren. Weitere Funktionalitäten - beispielsweise 
das Starten der generierten Aufgabe in der Aufgaben-Vorschau der IDE - sind ebenfalls für den 
Werkzeugentwickler verfügbar.
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
der IDE - beispielsweise das Starten der generierten Aufgabe in der Aufgaben-Vorschau der IDE - sind 
ebenfalls für den Werkzeugentwickler verfügbar.

Das Realisieren von Werkzeugen auf diese Art und Weise hat zahlreiche Vorteile:
-   Werkzeuge werden einheitliche und benutzerfreundlich zur Verfügung gestellt
@@ -45,14 +46,15 @@

Dabei darf der MathCoach-Server **nicht** fest in die URL eincodiert werden. Andernfalls
kann es zu Problemen kommen, wenn das Werkzeug auf unterschiedlichen Server bereitgestellt 
wird. Bei korrekter Verwendung steht die IDE API nun durch die globale Varialbe `MC` zur 
Verfügung - [Dokumentation der IDE API](./interfaces/mathcoach.api.html).
wird oder ohne IDE lauffähig sein soll. Bei korrekter Verwendung steht die IDE API nun 
durch die globale Varialbe `MC` zur Verfügung - [Dokumentation der IDE API](./interfaces/mathcoach.api.html).

> **Hinweis**: Es steht **ausschließlich** die API, welche über die globale Variable `MC`
> definiert ist, zur Verfügung! Hilfsfunktionen wie `Helpers.enableOfflineUsageIfNecessary()` 
> sind grundsätzlich nicht verfügbar und müssen vom Werkzeugentwickler eingebunden 
> werden - siehe "Hilfunktionen für Werkzeug-Entwickler" weiter unten.


> **Hinweis**: Erst, wenn das Werkzeug in die IDE integriert und aus dieser heraus
> gestartet wurde, kann die IDE API verwendet werden! Soll das Werkzeug auch ohne die 
> IDE nutzbar sein (z.B. zum Testen), muss dies bei der Implementierung berücksichtigt
@@ -168,6 +170,11 @@

![Demo](media/usage_tool_developer.gif)

*Ü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
@@ -175,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.
@@ -200,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
@@ -234,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.

    {
        ...
@@ -258,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`  |