# Visualisierung *multi-level bar chart array*

## Entwicklungsumgebung

Um dieses Projekt zu ändern oder weiterzuentwickeln, werden [`nodejs`][nodejs] und `npm` benötigt. Die Abhängigkeiten werden wie üblich per `npm install` installiert.

Für die Entwicklung wurden Teile von ES6 verwendet und mit [`rollup`][rollup], [`babel`][babel] und [`postcss`][postcss] transpiliert. Als *Build Management Tool* werden einfache `npm` Scripts verwendet.

`npm run watch` beispielsweis startet den Entwicklungsserver, transformiert Javascript und CSS Dateien bei Änderungen für das *Development* Target und lädt die Visualisierung im Browser.

Die folgenden Scripts sind in `package.json` definiert und können entsprechend mit `npm run …` ausgeführt werden:

```
- prepare         Wird ausgeführt, nachdem `npm install` aufgerufen wurde. In diesem Schritt werden die statischen Abhängigkeiten erstellt.
- build           Generiert Javascript und CSS Dateien (einmalig) und kopiert alle generierten Dateien inklusive html-Dateien in das Verzeichnis `dist`.
- build:data      Transformiert die Rohdaten in eine JSON-Datei für die Visualisierung.
- build:html      Generiert HTML Dateien für Visualisierung und umgebenden Text.
- build:static    Generiert die von der Anwendung benötigten JSON- und HTML-Dateien.
- build:dev       Generiert Javascript und CSS Dateien für einen *Development Build*.
- build:prod      Generiert Javascript und CSS Dateien für einen *Production Build*.
- watch           Startet den Entwicklungsserver führt bei Änderungen einen Development Build durch.
```

In der Datei `rollup.config.js` werden die Konfigurationen für `rollup` und `postcss` dynamisch generiert. Für den *Development Build* werden SourceMaps erstellt, dagegen werden Javascript und CSS Dateien für den *Production Build* mit [`terser`][terser] bzw. [`cssnano`][cssnano] optimiert.

Die HTML-Dateien werden von einem nodejs Script für das entsprechende *Target* generiert (momentan kann man die Sinnhaftigkeit bezweifeln, nachdem nur die geladenen Resourcen verschieden benannt werden). Leider ist HTML5 mit dem Versuch [gescheitert, HTML imports zu standardisieren][html5-imports]. Als pragmatische Alternative, und um möglichst flexibel zu bleiben, wurde daher entschieden, die eigentliche Visualisierung per `iframe` in der umgebenden Webseite einzubetten.

Für einen vereinfachten Workflow wird hier der Rahmentext für diese Seite aus einem Markdown Dokument in HTML konvertiert. Der darin enthaltene `iframe` *Tag* wird dynamisch konfiguriert und das Ergebnis in einer HTML-Datei gespeichert.

Die Datei `config.json` enthält die Konfigurationen sowohl zum Generieren der HTML-Dateien als auch für die Erstellung der Javascript- und CSS-Dateien.

Nach dem Ausführen eines *Builds* sind alle Dateien, die für die Funktionalität der Website / Web App erforderlich sind im Verzeichnis `dist` zu finden:

```
├── index.html                            Diese HTML-Seite ist der Einstiegspunkt und wird vom Web-Server ausgeliefert
├── risk-ladder.html                      Die Visualisierung wird in einem iframe in der index.html eingebunden
├── css
│   ├── index.css                         Stylesheet für die umgebende Webseite
│   └── main[.min].css                    Stylesheet für die Visualisierung
├── data
│   ├── data_de.json                      Daten der Visualisierung (deutsch)
│   └── data_en.json                      Daten der Visualisierung (englisch)
├── fonts
│   ├── ASAP                              Fonts für die Visualisierung
│   ├── montserrat                        Font für Überschriften der umgebenden Seite (wird entfallen)
│   └── lora                              Font für den Fließtext der umgebenden Seite (wird entfallen)
├── img
│   ├── BMJV_Web_Master_de_WBZ.png        BMJV Logo
│   ├── HardingCenter_Logo_de_RGB.png     Harding Zentrum Logo
│   └── mpib.png                          Max-Planck Institut fuur Bildungsforschung Logo
└── js
    ├── main.min.js                       Javascript der Visualisierung
    ├── blob-stream.min.js                Wird von pdfkit benötigt
    └── pdfkit.min.js                     Fettleibige Bibliothek zum generieren von PDF Dateien im Browser  
```

Wird ein Webserver konfiguriert, dieses Verzeichnis auszuliefern, sollte die Visualisierung enstsprechend erreichbar und funktional sein.

## Verzeichnisstruktur
```
├── README.md
├── assets
│   ├── css
│   │   └── index.css                               // Stildefinitionen der umgebenden HTML Seite
│   ├── fonts
│   │   ├── Asap-Bold.ttf
│   │   ├── Asap-Italic.ttf
│   │   ├── Asap-Regular.ttf
│   │   ├── AsapCondensed-Regular.ttf
│   │   ├── lora
│   │   │   ├── Lora-Regular.ttf
│   │   │   └── SIL\ Open\ Font\ License.txt
│   │   └── montserrat
│   │       ├── Montserrat-SemiBold.otf
│   │       └── SIL\ Open\ Font\ License.txt
│   ├── img                                         // Logos für die umgebende HTML Seite
│   │   ├── BMJV_Web_Master_de_WBZ.png
│   │   ├── HardingCenter_Logo_de_RGB.png
│   │   ├── jobloss.png
│   │   └── mpib.png
│   └── js                                          // Externe Javascript Bibliotheken
│       ├── blob-stream.min.js
│       ├── lunrjs
│       │   ├── lunr.de.js
│       │   ├── lunr.js
│       │   └── lunr.stemmer.support.js
│       └── pdfkit.min.js
├── bin
│   ├── prepareData.js                              // Generiert json Datei aus Rohdaten
│   └── preprocess.js                               // Generiert HTML Dateien für Visualisierung und umgebendes HTML
├── build.json                                      // Build Konfiguration
├── data                                            // Rohdaten
│   ├── jobloss_de.tsv
│   └── jobloss_en.tsv
├── package.json
├── rollup.config.js                                // Build Prozess
└── src
    ├── css
    │   └── main.css                                // Stildefinitionen für Visualisierung
    ├── html
    │   ├── markdown
    │   │   └── index.md                            // Markdown für Kontextinformationen des umgebenden HTML
    │   └── skeletons
    │       ├── main.html                           // Template für umgebendes HTML
    │       └── visualisation.html                  // Template für Visualisierung
    └── js
        ├── logos                                   // Definitionen der Logos als Javascript Objekte für Einbindung als Vektorgrafiken im PDF
        │   ├── BMJV_logo.js
        │   ├── RA_logo_1280.js
        │   └── hc_logo.js
        ├── config.json                             // Konfiguration der Visualisierung
        ├── d3-custom.js                            // Definition der verwendeten Module von d3
        ├── main.js                                 // Implementierung der Visualisierung
        ├── pdfExport.js                            // Generieren des PDF
        └── search.js                               // Implementierung der Suche
```

## Wie ändere ich Inhalte und Daten?

### Texte und Labels

Texte und Labels können in der Datei `config.json` geändert werden. Dort ist sowohl der Text des Eingabefeldes der Suche, als auch die Texte zu den Detailinformationen und des PDFs definiert.

### Daten

Für diese Visualisierung sind die hierarchischen Rohdaten in der Datei `data/jobloss_[de|en].tsv` definiert. Bevor sie in der Visualisierung verwendet werden können, müssen sie in eine JSON Datei transformiert werden. Dies geschieht im Schrit `build:data` des Build Prozesses. Bei Beibehaltung der Struktur der Daten können diese so beliebig ausgetauscht werden. Alle Bezeichner der interaktiven Visualisierung werden aus diesen Daten gelesen.

## Historisches

Ursprünglich wurde diese Visualisierung von *Data Science & Stories* entwickelt (inzwischen in einem Ressort des [Tagesspiegel][tagesspiegel] aufgegangen).

[nodejs]: https://nodejs.org/
[rollup]: http://rollupjs.org/
[babel]: https://babeljs.io/
[postcss]: https://postcss.org
[terser]: https://terser.org
[cssnano]: https://cssnano.co
[html5-imports]: https://caniuse.com/#search=html%20imports
[tagesspiegel]: https://digitalpresent.tagesspiegel.de

[lunrjs]: https://lunrjs.com
[lunr-languages]: https://github.com/MihaiValentin/lunr-languages
