# 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