Einführung
Installation
Benötigt werden nodejs (https://nodejs.org/, liefert npm mit) und git (für Windows siehe https://gitforwindows.org/). Mit npm kann dann grunt (https://gruntjs.com/) mit dem folgenden Befehl aus der Kommandozeile (Windows: cmd.exe) installiert werden:
npm install -g grunt-cli
Für das Installieren der aktuellen Packete regelmäßig folgende Befehle in der Kommandozeile und im Wurzelordner vom ELP (mit package.json und Gruntfile.js) ausführen:
npm install
grunt
Entwicklung
Wichtige Kommandozeilen-Befehle für die Pflege des ELP:
| Befehle | Beschreibung |
|---|---|
npm outdated | Veraltete Packete anzeigen |
npm install | Packete installieren/updaten, ignoriert Packet-Versionen die potenzielle Änderungen nötig machen |
grunt | Macht die gesamte "Magie", u.a. bindet aktuelle Versionen von geladenen Packeten in das ELP ein |
npm install -g npm | Aktualisiert npm selbst |
npm-windows-upgrade --npm-version latest | Spezielles Tool um npm auf Windows zu aktualisieren, mehr Details: Seite des Tools |
Um Packet-Versionen zu installieren, die manuell angesehen und das EeLP eventuell angepasst werden muss, muss package.json manuell angepasst werden, im Anschluss installiert npm install die neue Version.
Dokumentation
Die Dokumentation ist mit docusaurus gestaltet. Die dafür geschriebenen Markdown-Dateien sind im Unterordner docusaurus\. Die JavaScript API-Referenz wird automatisch aus JsDoc-Style Kommentaren aus der JavaScript-Datei generiert. Um die Dokumentation unter documentation\ nach Änderungen an den Dateien in docusaurus\ anzupassen, sind folgende Befehle nötig:
| Befehle | Beschreibung |
|---|---|
npm run build | Updatet die Dokumentation unter documentation\. Wird im Unterordner docusaurus ausgeführt! |
npm run start | Startet einen lokalen Testserver welcher bei Änderungen in docusaurus\ direkt docusaurus\ anpasst. Wird im Unterordner docusaurus ausgeführt! |
npm run jsdoc2md | Passt die API-Referenz in docusaurus\docs\Entwickler\Javascript\api an Resources\Js\planer.js an. Wird im Wurzelverzeichnis ausgeführt! |
grunt copy:docs | Kopiert die Ausgabe von docusaurus in den documentation-Ordner. Bestandteil von grunt build. Wird im Wurzelverzeichnis ausgeführt! |
Packete
Ein Projekt wie das ELP kann einen solchen Funktionsumfang nur erreichen, indem es auf zahlreiche existierende, freie Packete zurückgreift. Wir bedanken uns an dieser Stelle bei jedem Mitwirkenden dieser Packete und an der gesamten Open-Source-Community.
Die aktuell benutzten JavaScript-Packete umfassen:
| Packet | Zweck |
|---|---|
| Bootstrap 3 | HTML-Framework |
| Bowser | Erkennung des Browsers um gezielte Meldungen und Hinweise geben zu können |
| Canvg | Reiner JavaScript-SVG parser, gerade auch genutzt um MathJax-Ausgaben zu Bildern zu konvertieren und damit exportieren zu können |
| CKEditor 5 | WYSIWYG-Editor um Nutzen die Eingabe von Formatierungen und Inhalten wie Bildern zu ermöglichen |
| CKEditor 4 | Fallback von CKEditor 5 für IE 10 |
| docx | Übernimmt den Export zu docx-Dateien |
| es6-promise-polyfill | Polyfill für die moderne promise-Syntax |
| file-saver | Standarisiert das Speichern von Datein |
| flatpickr | Schöner, schlichter und moderner Datum- und Zeitpicker |
| font-awesome | Viele Icons die wir nicht selbst erstellen mussten |
| fullcalendar | Der Kalender im Kalender-View |
| interactjs | Bisher vor allem um das Anpassen der Größe von textareas auch auf touch-Geräten zu ermöglichen, möglicherweise kann in Zukunft drag&drop vereinfachen |
| jimp | "Rettet" den Export von Bildern indem viele Bilder so verändert werden, dass pdfmake und docx damit umgehen können |
| jQuery | JavaScript-Framework, vor allem für events genutzt, insbesondere mit den namespaces |
| jszip | Nötig für docx, in Zukunft möglicherweise auch für andere Export-Formate |
| list.js | Für die Listen in der Infothek |
| lodash | Viele Utility-Funktionen |
| marked | Übersetzt die Markdown-Dateien der Infothek zu HTML welches die Browser verstehen können |
| mathjax | Bringt den Support für mathematische Gleichungen, vor allem für die Unterstützung von latex-artiger Syntax genutzt |
| moment | Leistungsfähigerer Umgang mit Datum und Zeit als das native Date-Objekt |
| pdfmake | Generiert die PDFs, großartiges Projekt! |
| rgb-color | Voraussetzung für pdfmake |
| select2 | Ersetzt die kaum anpassbaren Selectboxen durch gut aussehende und insbesondere stark konfigurierbares DOM |
| timepicker | @Deprecated, vor flatpicker genutzt |
| urijs | Vereinfacht den Umgang mit URIs |
| validator | Sammlung von Tests um Dateien für spezielle Formate zu untersuchen, insbesondere für URIs und Data-URIs genutzt |
| vex-js | Vereinfacht das dynamische Erstellen von Dialogfenstern |
Zur Entwicklung nutzen wir:
| ESlint | Zur Syntaxüberprüfung von JavaScript |
|---|---|
| Prettier | Sorgt dafür, dass ein Code-Style befolgt wird |
| Grunt | Als einheitliche Ebene um die Entwicklertools auszuführen |
| uglify | Für das Minifizieren und Zusammenfügen der JavaScript-Dateien |
| concat_css | Für das Minifizieren und Zusammenfügen der CSS-Dateien |
| less | Modernere und handlichere "Version" von CSS |
| docusaurus | Baut die Dokumentation aus markdown-Dateien |
| jsDoc | Für das Generieren der JavaScript API-Referenz |
Nicht aufgeführt sind Plugins, die vollständige Liste kann in ´package.json´ eingesehen werden.