Im Folgenden soll ein Überblick über das System gegeben werden. Dabei wird unter anderem das Grundgerüst, die Infrastruktur und die Anwendung der Komponenten erklärt.
Die folgende Abbildung veranschaulicht die Ordnerstruktur der Code-Components:
components/
├── dist/ <- kompilierte Version der Komponenten, aufgeteilt in:
│ ├── css/ <- CSS, unkomprimiert, komprimiert und mapping
│ ├── fonts/ <- Webfonts
│ ├── js/ <- JavaSkripte, unkomprimiert, komprimiert und mapping
├── dist-docs/ <- kompilierte Dokumentation
├── dist-test/ <- kompilierte HTML-Tests inkl. Bildmaterial
├── docs/ <- Sourcen der Dokumentation
├── grunt/ <- diverse Skripte für den Erstellprozess
├── src/ <- Sourcen der Komponenten, aufgeteilt in:
│ ├── fonts/ <- Webfonts
│ ├── icon/ <- divese grafische Sourcen, AI, SVG,...
│ ├── js/ <- JavaSkripte inkl. Unit-Tests
│ ├── scss/ <- SCSS Sourcen zur Erstellung von CSS
├── src-test/ <- HTML Test-Dateien inkl. BildmaterialDen Kern der Komponenten bildet Grunt, der JavaScript-Task-Runner. Er verwaltet die Aufgaben wie das Erstellen der Komponenten oder das Erstellen der Dokumentation. Grunt sowie seine Plugins werden mit dem Node-Package-Manager (npm) verwaltet. Da die verwendeten Pakete nur für die Entwicklung benötigt werden ist deren Abhängigkeit im Punkt "devDependencies" der Datei package.json festgelegt. Diese wird von npm benötigt.
npm, den Node Package Manager (Wird mit Node.js ausgeliefert, unsere Version: 1.3.11)
Die jeweiligen Installationsanweisungen sind auf den Herstellerseiten zu finden.
Öffnen Sie eine Shell.
(z.B. Mac Terminal oder Windows Git-Bash)
Begeben Sie sich anschließend in das Hauptverzeichnis der Komponenten.
(hier befindet sich die Datei package.json)
Zunächst muss grunt-cli installiert werden.
Es sorgt dafür, dass die lokale Installation von Grunt gestartet wird.
("lokal" meint in dem Fall das Grunt des Projekts)
grunt-cli bereits global installiert,
braucht es natürlich nicht nochmal installiert werden.
npm install -g grunt-cliNun kann Grunt mit all seinen Plugins installiert werden:
npm installBeim Installationsprozess mit npm werden dabei automatisch alle Abhängigkeiten die ebenfalls mit npm verwaltet werden mitinstalliert. Deshalb kann die Installation ein paar Minuten dauern.
Ist die Installation abgeschlossen steht der Kern der Komponenten. Manche der verwendten Plugins benötigen jedoch noch weitere Tools deren Installation nun erklärt wird:
SCSS-Compiler
Das Plugin grunt-contrib-sass das für die Umwandlung der SCSS-Dateien
in CSS-Dateien zuständig ist benötigt zur Ausführung den SASS-Compiler
der wiederum Ruby mit DevKit benötigt:
SASS-Compiler (unsere Version: 3.4.10)
gem install sass --version 3.4.10Die jeweiligen Installationsanweisungen sind auf den Herstellerseiten zu finden.
SCSS-Linting
Das Plugin grunt-scss-lint soll SCSS-Dateien auf ihre Syntax überprüfen.
Hierfür wird das Tool scss-lint benötigt. Es hat Ruby und den
Sass-Compiler als Installationsvoraussetzungen. Diese sollten aber bereits
installiert sein. So können Sie direkt scss-lint installieren:
scss-lint (unsere Version: 0.33.0)
gem install scss-lint --version="0.33.0"Unit-Testing
Die JavaScript-Komponenten werden mit dem Plugin grunt-contrib-qunit
durch automatischen Tests auf ihre Richtigkeit untersucht. Die Tests
werden von PhantomJS durchgeführt. PhantomJS hat je nach Betriebssystem
Abhängigkeiten die eventuell installiert werden müssen:
Jekyll für die Dokumentation (optional)
Soll die Dokumentation erstellt werden, wird zusätzlich Jekyll benötigt.
Da die Dokumentation außerdem sehr viele Code-Beispiele enthält
werden diese extra ausgezeichnet. Dies wird mit dem Code-Highlighter rouge
erledigt:
Jekyll / mit rouge als Code-Highlighter
gem install jekyll --version="2.2.0"
gem install rougeInstallationshilfe für Windows - Bitte die Versionen beachten!
Allgemeines Update
Wenn sich die Datei package.json ändert muss dafür gesorgt werden, dass veraltete npm-Pakete deinstalliert und neue Pakete installiert werden.
Das ermöglichen die folgenden Befehle:
Veraltetes deinstallieren:
npm pruneNeues Installieren:
npm installSollte es Probleme geben, dann hilft es eventuell vorher den npm-Cache zu leeren:
npm cache clearGrunt Update: Beim Update von grunt via
npm update grunt --save-devpassiert erstmal garnichts. Deshalb kann folgender Weg eingeschlagen werden:
npm uninstall grunt
npm install grunt --save-devWas zu einem Fehler führt:
npm ERR! peerinvalid The package grunt does not satisfy its siblings' peerDependenciesAllerdings ist hier nicht zu finden um welche Abhängigkeiten (dependencies) es handelt. Um das herauszufinden muss
npm installausgeführt werden. Dadurch erhält man folgende Paketübersicht:
npm ERR! peerinvalid Peer grunt-banner@0.2.1 wants grunt@~0.4.1
npm ERR! peerinvalid Peer grunt-contrib-clean@0.5.0 wants grunt@~0.4.0
npm ERR! peerinvalid Peer grunt-contrib-concat@0.3.0 wants grunt@~0.4.0
npm ERR! peerinvalid Peer grunt-contrib-connect@0.6.0 wants grunt@~0.4.0
npm ERR! peerinvalid Peer grunt-jscs-checker@0.3.2 wants grunt@0.4.2Diese Meldungen sind jedoch verwirrend, da er alle pakete mit ERR markiert. Fehlerhaft ist jedoch meist nur ein Paket. Beispiel:
grunt-jscs-checker@0.3.2 wants grunt@0.4.2Achtung! Es wird die genaue Version 0.4.2 verlangt. (Das Paket grunt-jscs-checker@0.3.2 war in unserem Test-Fall außerdem veraltet)
Mit der Installation des neuen Pakets grunt-jscs war das Problem dann behoben.
Installieren von grunt-jscs
Wichtig für Windows: die Git-Bash als Administrator ausführen! Sonst dürfen Ordner nicht erstellt werden.
dann:
npm cache clear
npm install grunt-jscs --save-devZur Erstellung der Komponenten sind in der Datei Gruntfile.js mehrere Tasks definiert die im Folgenden kurz erklärt werden:
Erstellen der kompletten Komponenten - Der DEFAULT Task
Mit diesem Task werden die Komponenten zunächst getestet und anschließend
distributiert. Der Paramter --force sorgt dafür, dass
der Task auch im Fehlerfall weitergeführt wird:
grunt --force@-moz-document
Fehler. Wir warten derzeit auf die Einarbeitung dieser Auszeichnung in den Test.
Testen der Komponenten
Das Testen der Komponenten ist der wohl aufwändigste Task.
Hier wird sowohl die Syntax geprüft, als auch Unit-Tests
durchgeführt:
grunt dist-docs --forceErstellen der JS-Dateien
grunt dist-jsErstellen der CSS-Dateien
grunt dist-cssErstellen der HTML-Dateien im Testordner
grunt dist-htmlErstellen der Komponenten inkl. Assets
Hier werden Schriftarten usw. mit distributiert.
grunt distDas Erstellen der dokumentation benötigt Jekyll. Bitte beachten Sie die Installationsanweisungen:
grunt dist-docsDie dokumentation selbst ist mit der markdown syntax verfasst. Es ist daher sinnvoll ein Werkzeug zu verwenden, welches Markdown beherrscht.
Beispiele:
Für die Entwicklung der Komponenten steht der watch-Task zur Verfügung:
grunt watchEr beobachtet für die Entwicklung relevante Dateien. Ändert sich eine dieser Dateien wird automatisch der nötigte Erstell-Task aufgerufen. Die Test-HTML-Dateien sind außerdem mit dem livereload-Script ausgestattet. Es sorgt dafür, dass sich der Browser automatisch neu lädt, wenn eine Änderung stattgefunden hat.