# Crime Visualisierung

## 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
├── crime.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  
```

Dieses Verzeichnis kann von einem Webserver ausgeliefert werden, um die Visualiserung online zur Verfügung zu stellen.

## Verzeichnisstruktur

```
├── bin
│   ├── crime.js                        // Generiert data.json aus crime.tsv
│   ├── preprocess.js                   // Generiert HTML Dateien für Visualisierung und umgebendes HTML
├── data
│   ├── context.md                      // Inhalt der umgebenden HTML Seite
│   └── crime.tsv                       // Rohdaten
├── html
│   ├── markdown
│   │   └── index.md                    // Markdown für HTML Seite mit Kontextinformationen
│   └── skeletons
│       ├── main.html                   // Template für umgebende HTML Seite
│       └── visualisation.htmL          // Template für HTML Seite der Visualisierung
├── package.json
├── rollup.config.js                    // Build Prozess
├── src
│   ├── config.json                     // Konfiguration der Visualisierung
│   ├── d3-custom.js                    // Definition der verwendeten d3 Module
│   └── main.js                         // Implementierung der Visualisierung
└── styles
    └── main.css                        // Stildefinitionen
```

## Wie ändere ich Inhalte und Daten?

### Texte und Labels

Der Text der umgebenden HTML Datei ist in `data/context.md` zu finden. Diese Markdown Datei wird im Schritt `build:html` zu HTML konvertiert. Gleichzeitig wird auch die Größe iframes festgelegt und die einzubindende HTML Datei der Visualisierung mit den entsprechenden Referenzen zu den Javascript und CSS Dateien erstellt.

Die statischen Labels der Visualisierung sind in `src/config.json` definiert. Alle anderen Informationen werden aus den Daten bezogen.

### Daten

Für diese Treemap Visualisierung sind die hierarchischen Rohdaten in der Datei `data/crime.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.

### Drop-Down Menüs

Die Werte in den Drop-Down Menüs sind derzeit noch im HTML-Template der Visualisierung definiert.

## 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
