understanding-relative-risks

Inhalt

• Einführung
• Übersicht der Module
• Verzeichnisstruktur
• Modul 5: Relative Risiken verstehen
• Entwicklungsumgebung
• Javascript
• Sass
• Bilddateien
• Entwicklungshistorie

Einführung

Das Projekt RisikoAtlas hat die Förderung der Risikokompetenz zum Ziel. Zu diesem Zweck wurden am Harding-Zentrum für Risikokompetenz am Max-Planck-Institut für Bildungsforschung digitale Werkzeuge entwickelt, die auf wissenschaftlichen Erkenntnissen beruhen. Neben interaktiven Visualisierungen evidenzbasierter Risikokommunikation, einer App zur Entscheidungsunterstützung und einer Browser-Erweiterung als Leseassistenz sind Lernvisualisierungen zur Verbesserung der Risikokompetenz Teil des Projektes. Das vorliegende Modul ist eines dieser sechs Lernmodule.

Die Lernmodule wurden ursprünglich entwickelt von kf interactive.

Übersicht der Module

Die folgende Liste gibt einen Überblick über die Ziele der Module:

1. Modul 1 -- Risiken vergleichen *
2. Modul 2 -- Diagramme verstehen *
3. Modul 3 -- Trends schätzen *
4. Modul 4 -- Stichproben verstehen (original: Rock 'n poll)
5. Modul 5 -- Relative Risiken verstehen *
6. Modul 6 -- Wachstumsprozesse verstehen

Alle mit einem * versehenen Module greifen über eine API auf eine Datenbank zu. Auf diese Weise rufen sie die benötigten Daten ab, und speichern andererseits Antworten der Benutzer, um ihnen den Vergleich zu Anderen zu ermöglichen. Für jedes dieser Module existiert auch eine offline-Version, die ausschließlich auf lokale Daten zugreift.

Verzeichnisstruktur

Im Wurzelverzeichnis liegen die für den Build Prozess notwendigen Konfigurationsdateien. Das Verzeichnis doc/ enthält detailliertere Dokumentationen zu einzelnen Aspekten des Projekts. Alle für die WebApp benötigten Dateien werden in public/ erstellt bzw. dorthin kopiert. Im src/ Verzeichnis befinden sich alle Quelldateien, Bilder und Fonts. Der tasks/ Ordner enthält Javascript-Dateien, die die Teilschritte des Build-Prozesses definieren.

Die grobe Struktur sieht folgendermaßen aus:

├── .editorconfig        // Konfiguration für Texteditoren
├── .babelrc             // Konfiguration von babel
├── .eslintrc.yml        // Konfiguration des Javascript Linters
├── .htmlhintrc          // Konfiguration des HTML Linters
├── .sass-lint.yml       // Konfiguration des Sass Linters
├── config.js            // Konfiguration des Build-Systems
├── gulpfile.babel.js    // gulp Datei, verwendet Definitionen unter `tasks/`
├── package.json         // npm Abhängigkeiten, Shortcuts für gulp tasks
├── doc/                 // Dokumentation in markdown
├── public/              // Zielverzeichnis für den Build-Prozess
├── src/                 // Quellverzeichnis
│   ├── fonts            // Font Dateien
│   ├── html             // HTML 'Templates'
│   ├── img              // Bilder und Sprites
│   ├── js               // Javascript Quelldateien
│   └── scss             // Sass stylesheets
└── tasks/               // Definitionen für den gulp Build-Prozess

Modul 5: Relative Risiken verstehen

Mit diesem Modul soll das Verständnis von relativen Risiken geschult werden.\ Dazu werden den Nutzern Multiple-Choice-Fragen gestellt, die durch animierte Icon Arrays illustriert werden. Die Auflösung wird gegebenenfalls (im 'online' Modus) mit dem Vergleich zu anderen Nutzern präsentiert.

Javascript Verzeichnisstruktur

Für einen besseren Überblick sind die Quell-Dateien mit kurzen Beschreibungen aufgelistet:

├── main.jsx                      // Einstiegspunkt für App *mit* Verwendung der API ("online mode")
├── main-offline.jsx              // Einstiegspunkt für App *ohne* Verwendung der API ("offline mode")
├── config.js                     // Globale Konfiguration der WebApp
├── components
│   ├── Index.jsx                 // Web App Haupt-Komponente
│   ├── FinalScreen.jsx           // Abschließende Ansicht
│   ├── QuestionScreen.jsx
│   ├── TitleScreen.jsx           // Einleitende Ansicht
│   └── partials
│       ├── BubbleChartItem.jsx   // d3 Visualisierungen
│       ├── HeaderLightItem.jsx
│       ├── IntroItem.jsx         // Einführung zu den Fragen
│       ├── QuestionItem.jsx      // Benutzereingaben für Fragen
│       ├── ScoreItem.jsx         // Auflösung / Erklärung zu den Fragen
│       └── VoteItem.jsx          // Ergebnisse anderer Nutzer
├── content
│   ├── module.json               // Definition der Labels und Texte des User Interfaces
│   └── questions.json            // Definition der Multiple Choice Fragen
├── d3
│   ├── bar.js                    // Balkendiagramm für Vergleich mit anderen Nutzern
│   ├── bubblechart-decolor.js
│   ├── bubblechart-divide-gradual.js
│   ├── bubblechart-divide.js
│   ├── bubblechart-reduce.js
│   ├── bubblechart.js
│   └── defs.js
├── services
└── utilities
    ├── api.js                    // API zum Lese- und Schreib-Zugriff auf die Datenbank
    ├── enableTouch.js
    ├── fonts.js
    ├── formatter.js
    └── randomizer.js

Wie ändere ich Inhalte und Daten?

Labels

In module.json werden die umgebenden Texte definiert:

{
  "title": "Prozent von was??",
  "introtext": "Täglicher Wurstkonsum erhöht Darmkrebsrisiko um 18 %.\nDamit steht dieses Risiko auf der gleichen Gefahrenstufe der Weltgesundheitsorganisation WHO wie Asbest und Rauchen.",
  "introContinue": "Worum geht es hier?",
  "next": "Erklärung",
  "start": "Start",
  "restart": "Neustart",
  "percent": "18 %",
  "prediction": "mehr Darmkrebsrisiko bei erhöhtem Wurstkonsum",
  "conclusion": "Was haben Sie gelernt?",
  "finalTitle": "Fragen Sie sich immer, bei jeder Prozentangabe",
  "finalSlogan": "„% von was“?",
  "finalText": "Was ist „was“ genau?\nWie häufig kommt etwas normalerweise sowieso vor?\nDann lebt sich‘s viel entspannter.",
  "reference": {
    "source": "Quelle",
    "author": "WHO",
    "year": "(2015)",
    "title": "Links between processed meat and colorectal cancer.",
    "url": "http://www.who.int/mediacentre/news/statements/2015/processed-meat-cancer/en/"
  },
  "sausageEater": "Wurstesser",
  "mainstreamEater": "Durchschnittsesser",
  "usersRight": "Wie viele der anderen Nutzer lagen richtig?"
}

Hier können Titel, Einleitungstext und Zusammenfassung angepasst werden. Auch die Labels der Buttons sind dort festgelegt.

Fragen

In src/js/content/question.json werden die Fragen definiert:

{
  "intro": "Haben Sie sich dazu auch mal folgende Frage gestellt?",
  "title": "Welche Wurst?",
  "answers": [
    {
      "id": 1,
      "antwort": "Verarbeitetes Fleisch",
      "korrekt": true
    },
    {
      "id": 2,
      "antwort": "Rotes Fleisch",
      "korrekt": false
    },
    {
      "id": 3,
      "antwort": "Geräuchertes Fleisch",
      "korrekt": false
    },
    {
      "id": 4,
      "antwort": "Weißes Fleisch",
      "korrekt": false
    }
  ],
  "description": "Verarbeitetes Fleisch ist Fleisch, das durch Verarbeitungsprozesse wie Salzen, Räuchern, Reifen bzw. Fermentieren oder andere Verfahren verändert wurde, um den Geschmack zu verbessern oder es haltbar zu machen. Meistens sind Schweine-, Rind- oder Geflügelfleisch, aber auch Innereien enthalten. Wurstwaren, Schinken, Hackfleischprodukte und Fleischkonserven sind verarbeitetes Fleisch.",
  "onext": "Worum geht es hier?",
  "next": "Nur wie viel hiervon ist denn zu viel?"
},

Metadaten wie Titel ("title"), Einleitungstext ("intro"), Beschreibung ("description") und die Labels der Buttons können hier angepasst werden. Außerdem sind die Antwortoptionen definiert mit Label ("antwort") und der Information, ob die jeweilige Option wahr ist ("korrekt"). Die Auswertung geschieht immer sobald eine Option ausgewählt wurde, daher kann immer nur eine Antwort richtig sein.

Build Tool Chain

In diesem Abschnitt werden die technischen Voraussetzungen für die Erstellung von im Browser lauffähigem Code und und die Installation und Verwendung der Entwicklungsumgebung erläutert.

Voraussetzungen

Dieses Projekt wurde entwickelt auf Basis von nodejs unter Verwendung von npm als Paket-Manager. Mit den folgenden Versionen wurde zuletzt getestet:

nodejs: v14.4.0
   npm:  6.14.4

Alle Abhängigkeiten sind definiert in der npm Konfigurations-Datei package.json. Wie üblich werden diese installiert mit dem Befehl npm install. Als Task-Manager dieses Projekts wird gulp dabei global installiert.

Für das Erstellen der Dokumentation aus den einzelnen Markdown-Dateien, die im Verzeichnis doc/ liegen, wird pandoc verwendet. Dieses ist für viele Betriebssysteme und Distributionen verfügbar, muss aber gesondert installiert werden.

Konfiguration

Die Build Konfiguration ist in config.js im Wurzelverzeichnis definiert. Außerdem sind in der Datei package.json die zu unterstützenden Browser-Versionen für autoprefixer angegeben.

Konfigurationen für Babel, Editoren und Linter sind ebenfalls im Wurzelverzeichnis zu finden:

       babel: .babelrc
editorconfig: .editorconfig
        html: .htmlhintrc
  javascript: .eslintrc.yml
        sass: .sass-lint.yml

Erstellen von Builds

Alle Schritte zum Erstellen von Builds sind in den Javascript-Dateien unter tasks/ definiert und werden von der gulp Konfigurationsdatei gulpfile.babel.js importiert. Dort sind die Teilschritte in Tasks zusammengefasst, die man am häufigsten benötigt.

$ gulp        # Default task, Kurzform für 'gulp watch'
$ gulp build  # Erstellt einen Development Build
$ gulp watch  # Erstellt einen Development Build und startet den Entwicklungsserver

Build Target

Die Unterscheidung zwischen Development und Production Build wird anhand der nodejs Umgebungsvariable NODE_ENV vorgenommen. Ohne diese Angabe wird immer ein Development Build erstellt (siehe config.js). Für das Development Target werden Javascript und CSS zusätzlich mit Sourcemaps versehen, für die Produktiv-Version dagegen werden die Dateien von unnötigem Ballast befreit (terser für Javascript, cssnano für CSS).

# Erstellen eines Production Build
$ NODE_ENV=production gulp build

Build Mode

Zusätzlich gibt es für dieses Projekt die Unterscheidung zwischen 'online' und 'offline' Versionen. Im Fall der 'online' Version wird auf eine API zugegriffen, um die benötigten Inhalte zu laden, und um die Antworten der Benutzer zu speichern, um ihnen einen Vergleich mit Anderen zu ermöglichen. Diese Unterscheidung kann beim Aufruf von gulp auf der Kommandozeile mit einem Parameter getroffen werden. Soweit verfügbar, wird standardmäßig der 'online' Modus verwendet, (siehe config.js).

# Erstellen eines Development Build für den 'offline' Modus
$ gulp --api-mode=offline

npm Shortcuts

Da die Handhabung mit dem Setzen der Umgebungsvariable und das Übergeben des Parameters etwas umständlich ist, sind in package.json npm ein paar Shortcuts definiert, z.B.:

# Erstellen eines Production Build für den 'offline' Modus per gulp Script
$ NODE_ENV=production gulp build --api-mode=offline

# Erstellen eines Production Build für den 'offline' Modus per npm Script
$ npm run build:prod:offline

Erstellen der Dokumentation

Die Dokumentation in einzelne Markdown-Dateien aufgeteilt, die im Verzeichnis doc/ liegen. Zum Erstellen einer zusammenhängender Dokumentation sind folgende npm Scripts definiert, die auf pandoc basieren:

npm build:doc       // Kurzform für das Erstellen der Dokumentation im bevorzugten Ausgabeformat (Standard: Markdown)
npm build:doc:html  // Erstellt eine HTML Dokumentation als `index.html` in `doc/html`
npm build:doc:md    // Erstellt eine zusammenhängende Dokumentation als `readme.md` im Wurzelverzeichnis

Konventionen

Der Javascript Code ist in ES6 (bzw. ES2015) verfasst. Als CSS-Preprocessor wird Sass mit der scss Syntax verwendet. Die Code Style Konventionen wurden von den ursprünglichen Entwicklern übernommen und nur an wenigen Stellen leicht angepasst.

Das Projekt verwendet editorconfig für die Integration dieser Konventionen in Editoren, die entsprechende Datei heißt .editorconfig.

Für die statische Überprüfung des Quellcodes werden folgende Linter verwendet:

• Javascript: eslint
• Sass: sass-lint
• HTML: HTMLHint

Die zugehörigen Konfigurationsdateien befinden sich im Root-Verzeichnis, wie oben in der Auflistung angegeben.

Javascript

Verwendete Bibliotheken

Die grundlegende Architektur der WebApp wurde implementiert auf Basis von preact, von den Entwicklern beworben mit

Fast 3kB alternative to React with the same modern API.

Es ist allerdings keine exakte Reimplementierung, weswegen ein eigener Teil der Dokumentation der Erläuterung der Unterschiede zu React gewidmet ist.

Für Visualisierungen wird die großartige und weit verbreitete Bibliothek D3.js verwendet.

Verzeichnisstruktur

Die folgende Auflistung gibt einen groben Überblick über die Verzeichnisstruktur der Javascript Quelldateien in src/js/. Als Einstieg dient main.jsx bzw. main-offline.jsx für den "offline" Modus. config.js ist die zentrale Konfigurationsdatei der WebApp. In components liegen die Komponenten der preact-WebApp. Der Quellcode für die D3-Visualisierungen befindet sich unter d3.

├── main.jsx            // Einstiegspunkt für App in "online" Modus
├── main-offline.jsx    // Einstiegspunkt für App in "offline" Modus
├── config.js           // Konfiguration der WebApp
├── components/         // Verzeichnis für (p)react Komponenten
│   ├── Index.jsx       // Web App Haupt-Komponente
│   └── partials/       // Vezeichnis für Teilkomponenten
├── content/            // Verzeichnis für "offline" Inhalte
├── d3/                 // d3 Module
└── utilities/          // Verzeichnis für Hilfs-Bibliotheken und Werkzeuge

Sass

Zum Kompilieren von Sass zu CSS wird gulp-sass verwendet, das node-sass benutzt, welches wiederum auf libsass basiert. node-sass hat sich beim wiederholten gedankenlosen Aktualisieren von nodejs und / oder npm als notorischer Nerventöter herausgestellt, daher an dieser Stelle der Verweis zur Troubleshooting Dokumentation von node-sass. Meist reichte im Falle eines Problems aber ein npm rebuild node-sass.

Struktur

In der Datei main.scss werden alle Stile eingebunden, die in den Partials definiert werden, woraus die endgültige CSS-Datei generiert wird. Die Struktur des src/scss Verzeichnisses sieht folgendermaßen aus:

├── base     // Stile für HTML Elemente
├── config   // Globale Variable
├── modules  // Stile für Module
└── tools    // Definierte *mixins* und Funktionen

Konventionen, Techniken und Tools

Generell wird eine "mobile first" Strategie verfolgt. Als Standard-Einheit wird rem verwendet, auf deren Grundlage die Basis-Einheit definiert ist. Da sich alle Größen auf diese Einheit beziehen sollten, wird so das Skalieren des Layouts erleichtert.

Sass wird in diesem Projekt mit der scss-Syntax verwendet. Stilistisch ist es in "oldschool BEM-Style" gehalten, Zitat der ursprünglichen Entwickler. Sie beziehen sich zudem auf bestimmte Guidelines:

Hugo Giraudel wrote an awesome piece on everything you need to know about Sass, it's called Sass Guidelines and you should really have a look at it. I agree with this guideline in almost all points, but I try to keep something more simple, and some things more strict, the linter will let you know :)

ʕ̡̢̡ॢ•̫͡ॢ•ʔ̢̡̢

Regeln mit Browser-spezifischen Präfixen (vendor prefixes) werden dem CSS automatisch durch autoprefixer hinzugefügt. Die Liste der zu unterstützenden Browser ist in package.json unter browserslist zu finden.

Bilddateien

Alle in diesem Projekt verwendeten Bilddateien befinden sich unter src/img/.

Icons in Form von SVG-Dateien befinden sich im Unterordner src/img/sprites und werden im Build-Prozess mittels gulp-svg-sprite zu einem Sprite zusammengefasst. Sie wie folgt in HTML referenziert werden:

<svg class="icon  icon--arrow-left">
  <use xlink:href="assets/img/sprites.svg#icon--arrow-left"/>
</svg>

Stil-Definitionen für Icons sind unter src/scss/modules/_icons.scss zu finden. Für die Unterstützung von Fragmentbezeichnern (fragment identifier) in Internet Explorer wird svgxuse verwendet.