HTML5-Tutorium: JavaScript: Hello World 04

Dieser Artikel wird derzeit von einem Autor gründlich bearbeitet. Die Inhalte sind daher evtl. noch inkonsistent.

Dieser Artikel erfüllt die GlossarWiki-Qualitätsanforderungen nur teilweise:

Korrektheit: 3 (zu größeren Teilen überprüft)

Umfang: 4 (unwichtige Fakten fehlen)

Quellenangaben: 3 (wichtige Quellen vorhanden)

Quellenarten: 5 (ausgezeichnet)

Konformität: 3 (gut)

Vorlesung WebProg

Inhalt | Teil 1 | Teil 2 | Teil 3 | Teil 4 | Teil 5 | Teil 6 | Vue 1 | Vue 2 | Vue 3 | Vue 4 | Vue 5 | Vue 6 Musterlösung: index.html (SVN-Repository)

Anwendungsfälle (Use Cases)

Gegenüber dem dritten Teil des Tutoriums ändern sich die die Anwendungsfälle nicht. Die Anwendung leistet also genau dasselbe wie zuvor.

In diesem Teil des Tutoriums geht es darum, die Anwendung zu verbessern, so dass sie schneller ausgeliefert werden kann.

Erstellen eines neuen Projektes

Erstellen Sie ein neues Projekt „HelloWorld04“ und legen Sie dieses in Ihrem Repository ab. Kopieren Sie anschließend alle Dateien aus dem dritten Teil des Tutoriums, passen Sie den Titel in der HTML-Datei an und committen Sie abermals.

Erstellen einer Ordnerstruktur

Grundsätzlich gilt auch bei der Programmierung: Ordnung ist das halbe Leben.

Web-Anwendungen werden sehr schnell sehr groß. Also sollte man sich eine geeignete Ordnerstruktur überlegen. Üblicherweise legt man CSS-Dateien in einen Ordner namens „css“ und JavaScript-Dateien in einen Ordner namens „js“. Sollten es viele CSS- und/oder JavaScript-Datein werden, legt man im entsprechenden Ordner geeignete Unterordner an.

Legen Sie im Root-Verzeichnis Ihres Projektes folgende Ordner an:

• web (Der Inhalt dieses Ordners kommt später auf einen echten Web-Server.)
• src (Dieser Ordner enthält die unkomprimierten CSS- und JavaScript-Dateien.)
• doc (Dieser Ordner enthält die Projektdokumentation.)
• conf (Dieser Ordner enthält Projektkonfigurationsdateien mit Aus

Legen Sie innerhalb der Ordner „web“ und „src“ jeweils zwei weitere Ordner an: „css“ sowie „js“ .

Öffnen Sie im Editorbereich die Datei „index.html“ und verschieben sie in denr Ordner „src“. Verschieben sie anschließend die Dateien „main.css“ und „main.js“ in die passenden Ordner „src/css“ bzw. „src/js“. Sie werden feststellen, dass die Verweise in den Link- und Script-Elementen der Datei „index.html“ automatisch angepasst werden. Verschieben Sie nun die Datei „index.html“ in den Ordner „dist“.

Das Ergebnis dieser Aktion ist, dass Ihre Web-Anwendung nicht mehr im Root-Verzeichnis des Projektes liegt, sondern (sauber strukturiert) in zwei Unterordnern. Daher ist es möglich, im Root-Verzeichnis des Projektes weitere projektspezifische Ordner und Dateien anzulegen wie „conf“ und „doc“, die später nicht auf den Web-Server, auf dem die Anwendung schließlich laufen soll, kopiert werden.

Laden der CSS- und der JavaScript-Dateien

Eine Web-Anwendung funktioniert nur – wie Sie bereits erfahren haben –, wenn nicht nur die HTML-Datei, sondern auch die zugehörigen CSS- und JavaScript-Dateien geladen werden. Allerdings gibt es dabei ein Problem: Die CSS- und JavaScript-Dateien werden im Laufe der Zeit immer zahlreicher und/oder größer. Diese Dateien zu laden, dauert seine Zeit.

In der aktuellen Version der Web-Anwendung stehen diese Verweise auf diese Dateien im head-Bereich des Dokuments. Dieser wird vollständig geladen, bevor der body-Bereich eingelesen wird. Das heißt aber, dass der Browser keine Inhalte des HTML-Dokuments darstellen kann, solange er die JavaScript- und CSS-Dateien lädt. Wenn dies zu lange dauert, verliert der Besucher die Geduld und verläßt die Seite vorzeitig.

Besser wäre es daher andersherum vorzugehen: Es wird zuerst der body-Bereich geladen und dann die JavaScript- und die CSS-Dateien. Im Falle von JavaScript ist das durchaus sinnvoll, aber im Falle von CSS hat das den Effekt, dass der Browser keine Layout-Vorgaben erhalten hat, wenn er mit dem Rendern der Seite beginnt. Also verwendet er die browserspezifischen Defaultwerte. Das heißt, die Seite sieht zunächst ganz anders aus, als vom Designer geplant. Wenn dann die CSS-Dateien geladen wurden, wird die Seite erneut gerendert und verändert ihr Aussehen. Auch das ist verwirrend und wirkt unprofessionell.

Was also machen?

CSS-Dateien

Für CSS-Dateien empfiehlt Google ernsthaft, die Link-Element ganz ans Ende der HTML-Datei zu stellen, also nach dem schließenden html-Tag. Damit das Problem mit dem falschen Layout nicht auftritt, sollen wichtige CSS-Style-Befehle direkt – d. h. als CSS-Befehle innerhalb eines stxle-Elements – in die HTML-Datei eingefügt werden.

Von beiden Vorschlägen rate ich dringend ab. Der erste Vorschlag ist nicht HTML-konform, ja noch nicht einmal SGML-konform. Es mag sein, dass diverse Browser diese Syntax verstehen, korrekt ist sie trotzdem nicht. Der zweite Vorschlag hat zur Folge, dass Struktur (HTML) und Layout (CSS) vermischt werden. Dies war einer der Kardinalfehler von frühen HTML-Versionen aus der Zeit, bevor es das CSS-Format gab. Tun Sie das nicht.

Gehen Sie so vor, wie es unter Multimedia-Programmierung: Best Practices beschrieben ist.

In unserer Anwendung haben wir bislang alles richtig gemacht, bis auf die fehlende automatische Komprimierung. Diese wird weitrt unten beschrieben.

JavaScript-Dateien

Für JavaScript-Dateien empfiehlt Google ebenfalls, diese nicht schon zu Beginn zu laden. Dieser Vorschlag ist sehr sinnvoll.

Entfernen Sie das script-Element aus dem HTML-Header-Bereich und fügen Sie es vor dem schließenden body-Tag ein:

   ...
   <script type="text/javascript" src="../src/js/main.js"></script>
</body>

Node.js

Dieses Tutorium befasst sich zwar nicht mit der Erstellung von Node.js-Anwendungen, aber trotzdem benötigen wir Node, da für die Komprimierung von Dateien und das automatische Erstellen von JavaScript-Dokumentationen derartiege Anwendungen zum Einsatz kommen.

Installieren Sie zunächst Node.js: https://nodejs.org/en/, Version 6.x. Dieverse Versionen finden Sie unter https://nodejs.org/en/download/. Achten Sie darauf, dass die Option „Add to PATH“ ausgewählt wurde.

Starten Sie WebStorm neu und öffnen Sie das Terminal, um zu testen, ob node funktioniert:

• Klick auf Icon in der linken unteren Ecke → Terminal
• Geben Sie Folgendes ins Terminal ein: node --version

Wenn Node.js korrekt installiert und der Pfad mit den node-Binaries in die Systemvariable PATH eingetragen wurde, sollte die Versionsnummer von node ausgegeben werden.

Sie werden feststellen, das Node.js zum Großteil über Konsolbefehle gesteuert wird. Zu Beginn mag das für eingefleischte Klickibunti ungewohnt sein, aber Sie werden sich schnell daran gewöhnen.

Tipp
Profis verwenden unter Windows lieber ein Terminal, dass eine Unix-Shell simuliert. (Unter Linux und Mac OS X ist das nicht notwendig. Dort läuft sowieso schon eine UNIX-Shell.)

Installieren Sie „Git for Windows“ (https://git-for-windows.github.io/). In diesem Paket ist die „Git BASH“ enthalten. Das ist eine Terminal-Anwendung, die eine Linux-Bash emuliert und zahlreiche nützliche Befehle wie „which“, „vi“ ( :-) ) etc. zur Verfügung stellt.

Öffnen Sie nun ein beliebiges Terminal (WebStorm-Terminal, Git Bash, Mac-OS-X-Terminal ...) und geben Sie folgenden Befehl ein

npm install -g bower grunt-cli jsdoc ink-docstrap yuglify node-minify

Damit werden die wichtigsten Node.js-Pakete gobal (Option „-g“) installiert, die wir im Folgenden noch benötigen. (OK, bower wird noch nicht benötigt. Das Paket ist aber so gut, dass wir es sicher noch brauchen werden.) Die globale Installation hat zur Folge, dass jedes Projekt auf diese Pakete zugreifen kann, Pakete also nicht mehrfach installiert werden.

Installieren Sie außerdem lokal im Root-Verzeichnis Ihres Projektes „HelloWorld04“ die nachfolgenden Pakete. (Dazu müssen Sie in Ihrem Terminal mittels des UNIX-Befehls „cd“ in das Root-Verzeichnis Ihres Projektes wechseln. Das aktuelle Verzeichnis des WebStorm-Terminals ist bereits dieses Root-Verzeichnis. Hier brauchen Sie also i. Allg. keinen Verzeichniswechsel vorzunehmen.)

npm install grunt grunt-contrib-cssmin grunt-contrib-uglify ink-docstrap --save-dev

Die lokalen Node.js-Dateien werden in eniem Projektordner namens „node_modules“ abgelegt. Da Sie die darin enthaltenen Dateien jederzeit ganz einfach wiederherstellen können und es sich um wirklich viele (evtl. mehrere Tausend) ganz kleinde Dateien handelt und es daher sehr zeitaufwändig ist, sollten Sie den Ordner nicht ins Repository einfügen (Web-Storm bietet Ihnen das bei einem Commit auch gar nicht an). Außerdem sollten Sie Folgendes machen:

• Rechtsklick im Dateibaum auf „node-modules“ → Mark Directory as → excluded
• Rechtsklick im Dateibaum auf „doc“ → Mark Directory as → excluded

Beide Ordner enthalten Dateien, die nicht von Ihnen stammen. Diese Dateien können Fehler und Hinweise enthalten, veraltete Schnittstellen (“deprecated”) verwenden etc. (Oh ja, auch andere Programmierer machen Fehler. :-) ) Und wenn Sie diese beiden Orner nicht als „excluded markieren“, prüft WebStorm bei jedem Commit die darin enthaltenen Dateien und weist Sie auf jedes Problem hin. Das können so vile Probleme sein, dass Sie die Probleme in Ihren eigenen Datein vollkommen übersehen.

Automatische Generierung der Schnittstellenbeschreibung

Installieren Sie zunächst JSDoc:

• Öffnen Sie das WebStorm-Terminal.
• npm install -g jsdoc (installiert JSDoc als Node.js-Anwendung; das haben wir eigentlich schon gemacht, aber das macht nix :-) )
• npm install ink-docstrap (installiert ein JSDoc-Theme namens „docstrap“ ([1]); es gibt auch noch andere Themes für JSDoc)

Erstellen Sie im Projektordner „conf“ eine JSON-Datei namens „jsdoc.conf“. Fügen Sie in diese Datei folgenden Code ein:

{
  "tags":
  {
    "allowUnknownTags": true
  },
  "source":
  {
    "include":        ["./src/js"],
    "includePattern": ".+\\.js$",
    "excludePattern": "doc"
  },
  "plugins":
  [],
  "templates":
  {
    "systemName":      "WK_HelloWorld04",
    "footer":          "Created by Wolfgang Kowarschick",
    "copyright":       "2016",
    "navType":         "vertical",
    "theme":           "spacelab",
    "linenums":        true,
    "cleverLinks":     false,
    "monospaceLinks":  true,
    "collapseSymbols": true,
    "inverseNav":      false
  },
  "opts":
  {
    "template":    "node_modules/ink-docstrap/template",
    "encoding":    "utf8",
    "destination": "doc/jsdoc",
    "recurse":     true,
    "private":     true
  }
}

Ersetzen Sie im Attribut „footer“ meinen Namen durch Ihren, denn es ist Ihr Projekt, nicht meines. :-)

In dieser Datei wird festgelegt, wie die HTML-Dokumentation des Codes, die JSDoc erstellt, aussehen soll. Insbesondere ist das Template angegeben, das zur Erstellung dieser HTML-Dokuemnte verwendet werden soll. Es handelt sich um „inc-docstrap“, welches wir zuvor heruntergeladen haben. Von der Projektroot aus gesehen, befinden sich die Template-Dateien im Ordner „node_modules/ink-docstrap/template“.

Weitere Konfigurationsparameter werden unter http://usejsdoc.org/about-configuring-jsdoc.html beschrieben.

Sie können nun eine Dokumentation für Ihr Projekt erstellen:

• Öffnen Sie das WebStorm-Terminal.
• jsdoc -c conf/jsdoc.json

Nach kurzer Zeit sollte der Ordner „doc/jsdoc“ erstellt und mit Inhalten gefüllt worden sein. Sehen Sie sich die Datei „doc/jsdoc/index.html“ im Browser an. Diese enthält nicht viel, außer einem Drop-Daown-Menü „global“, in dem die drei von Ihnen erstellen globalen Funktionen „greet“, „greet_on_enter“ und „init“ enthalten sind. Klicken Sie auf eine dieser Funktionen.

Globale Speicherung der JSDoc-Templates

Wenn Sie „ink-docstrap“ nicht mittels

npm install ink-docstrap

sondern mittels

npm install -g ink-docstrap

installieren (so wie Sie das auch schon bereits getan haben), werden die Template-Dateien nicht im Projektordner, sondern im globalen npm-Ordner abgelegt. Das hat den Vorteil, dass Sie dieses Template für viele Projekte einsetzen können und es nicht bei jedem Projekt separat speichern müssen. Der Nachteil ist, dass in der Datei „conf/jsdoc.json“ den absoluten Pfad des globalen Ordners angeben müssen. Dieser Pfad sieht auf jedem Rechner anders aus. Bei mir lautet er beispielsweise:

c:/Users/kowa/AppData/Roaming/npm/node_modules/ink-docstrap/template

Das heißt, wenn man im Team an einem Projekt arbeitet, müsste man für jedes Teammitglied eine eigene JSDoc-Konfigurationsdatei anlegen, was nicht wirklich schön, aber doch machbar ist.

In der Musterlösung verwende ich die lokale Version „ink-docstrap“. Diese ist alledering nicht im Repository enthalten. Nachdem Sie die Musterlösung auf Ihren Rechner kopiert haben (Vergessen, wie's geht? Siehe HTML5-Tutorium: JavaScript: Hello World 04), müssen Sie im WebStorm-Terminal der Musterlösung noch folgenden Befehl ausführe:

npm update

Und schon sollten Sie die Dokumentation wie gewohnt erstellen können.

Sobald Sie „grunt“ konfiguriert haben, sollte „conf/jsdoc.json“ auch in Ihrem Projekt fehlende Node.js-PAkete nachinstallieren.

Erstellung der JSDoc-Dokumentation mittels Klickbunti

Falls Sie die Dokumentation icht immer über das Terminal erstellen möchten, können Sie in WebStorm einen neuen Menüeintrag erstellen, über den Sie die Erzeugung der HTML-Dokumentation starten können.

Sie müssen dazu den Pfad ermitteln, unter dem Ihre jsdoc-Datei zu finden ist. Unter Unix (Maac OS X, Linux, FreeBSD ...) lautet der Befehl, den Sie in ein Terminal eingeben müssen:

which jsdoc

Unter Windows funktioniert dieser Befehl nur in der Git BASH. Außerdem müssen Sie unter Windows den Bash-Pfad modifizieren, damit auch Windows etwas damit anfangen kann. Bei mir gibt dieser Befehl Folgendes aus:

/c/Users/kowa/AppData/Roaming/npm/jsdoc

Um jsdoc in WebStorm aufrufen zu können, müssen Sie in diesem Pfad „/c“ durch „c:“ und „jsdoc“ durch „jsdoc.cmd“ ersetzen. (Mac-User brauchen nichts zu ändern. :-) )

Erstellen Sie nun den neuen WebStorm-Menüeintrag:

• File → Settings → Tools → Extenal Tools
• Klick auf das Plus-Icon
  • Name: JSDoc
  • Group: Documentation
  • Description: Generates JavaScript documentation
  • Hacken bei allen Optionen (Options)
  • Hacken bei allen Show-in-Optionen (Show i) mit ausnahme von „Search results“
• Name: c:/Users/kowa/AppData/Roaming/npm/jsdoc.cmd (hier kommt Ihr zuvor ermittelter Pfad hinein)
• Name: -c $ProjectFileDir$/conf/jsdoc.json
• Name: $ProjectFileDir$
• OK
• OK

Nun finden Sie an mehreren Stellen in WebStorm einen neuens Menüpunkt Documentation mit einem Unterpunkt JSDoc:

• Hauptmenü : Tools → Documentation → JSDoc
• Rechtsklick auf Datei im Projekt-Dateibaum → Documentation → JSDoc
• Rechtsklick auf Datei im Editor-Tabmenü → Documentation → JSDoc

Wenn Sie auf einen dieser Unterpunkte „JSDoc“ klicken, erhalten Sie entweder eine Fehlermeldung ( :-( ) oder es wird eine neue Dokumentation erstellt (d. h., Sie haben alles richtig gemacht :-) ).

Um sicher zu gehen, können Sie versuchsweise den Ordner „doc“ gemeinsam mit seinem gesamten Inhalt löschen und JSDoc nochmals aufrufen.

Sicherung im Repository

Bevor Sie weitermachen: Haben Sie Ihre aktuelle Veriosn von Hello World 04 schon im Repository gesichert?

Wenn Sie möchten, können Sie die Ordner „doc“ und „node_modules“ zu Ihrem Repository hinzufügen:

• Klick auf den entsprechenden Ordner im Dateibaum → Subversion → Add to VCS

Wirklich nötig ist das nicht, da Sie beide Verzeichnisse ja jederzeit neu erstellen können (mittel „npm install ink-docstrap“ bzw.„JSDoc“). Die Endabgabe Ihrer Studienarbeit sollte allerdings einen doc-Ordner mit einer guten Schnittstellen-Dokumentation enthalten.

Automatische Komprimierung von CSS- und Javascript-Dateien

TO BE DONE

Quellen

2. Kowarschick (MMProg): Wolfgang Kowarschick; Vorlesung „Multimedia-Programmierung“; Hochschule: Hochschule Augsburg; Adresse: Augsburg; Web-Link; 2018; Quellengüte: 3 (Vorlesung)