hardingcenter
/
comparing-risks


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216
							<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <meta name="author" content="Tabea David tabea.david@kf-interactive.com" />
  <meta name="author" content="zitzmann@mpib-berlin.mpg.de" />
  <title>Dokumentation</title>
  <style>
    code{white-space: pre-wrap;}
    span.smallcaps{font-variant: small-caps;}
    span.underline{text-decoration: underline;}
    div.column{display: inline-block; vertical-align: top; width: 50%;}
    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
    ul.task-list{list-style: none;}
  </style>
  <link rel="stylesheet" href="css/github-markdown.css" />
  <link rel="stylesheet" href="css/github-syntax-highlight.css" />
  <!--[if lt IE 9]>
    <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
  <![endif]-->
</head>
<body>
<header id="title-block-header">
<h1 class="title">Dokumentation</h1>
<p class="author">Tabea David <a href="mailto:tabea.david@kf-interactive.com" class="email">tabea.david@kf-interactive.com</a></p>
<p class="author">zitzmann@mpib-berlin.mpg.de</p>
</header>
<p><link rel="stylesheet" href="css/cssgithub-markdown.css" /> <link rel="stylesheet" href="css/github-syntax-highlight.css" /></p>
<h2 id="table-of-contents">Table of contents</h2>
<ul>
<li><a href="#einführung">Einführung</a></li>
<li><a href="#übersicht-der-module">Übersicht der Module</a></li>
<li><a href="#verzeichnisstruktur">Verzeichnisstruktur</a></li>
<li><a href="#modul-2-diagramme-verstehen">Modul 2: Diagramme verstehen</a></li>
<li><a href="#build-tool-chain">Build Tool Chain</a></li>
<li><a href="#javascript">Javascript</a></li>
<li><a href="#sass">Sass</a></li>
<li><a href="#bilddateien">Bilddateien</a></li>
<li><a href="#entwicklungshistorie">Entwicklungshistorie</a></li>
</ul>
<h2 id="einführung">Einführung</h2>
<p>Das Projekt <a href="https://risikoatlas.de">RisikoAtlas</a> 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.</p>
<p>Die Lernmodule wurden ursprünglich entwickelt von <a href="https://www.kf-interactive.com">kf interactive</a>.</p>
<h2 id="übersicht-der-module">Übersicht der Module</h2>
<p>Die folgende Liste gibt einen Überblick über die Ziele der Module:</p>
<ol type="1">
<li><strong>Module01 – Risiken vergleichen</strong> <strong>*</strong></li>
<li>Module02 – Diagramme verstehen <strong>*</strong></li>
<li>Module03 – Trends schätzen <strong>*</strong></li>
<li>Module04 – Stichproben verstehen (original: <a href="http://rocknpoll.graphics/">Rock ’n poll</a>)</li>
<li>Module05 – Relative Risiken verstehen <strong>*</strong></li>
<li>Module06 – Wachstumsprozesse verstehen</li>
</ol>
<p>Alle mit einem <strong>*</strong> versehenen Module greifen über eine API auf eine Datenbank zu. Auf diese Weise rufen sie die benötigten Daten ab, und speichern andererseits Benutzerantworten, um Nutzern den Vergleich zu Anderen zu ermöglichen. Für jedes dieser Module existiert auch eine offline-Version, die ausschließlich auf lokale Daten zugreift.</p>
<h2 id="verzeichnisstruktur">Verzeichnisstruktur</h2>
<p>Im Wurzelverzeichnis liegen die für den Build Prozess notwendigen Konfigurationsdateien. Das Verzeichnis <code>doc/</code> enthält detailliertere Dokumentationen zu einzelnen Aspekten des Projekts. Alle für die WebApp benötigten Dateien werden in <code>public/</code> erstellt bzw. dorthin kopiert. Im <code>src/</code> Verzeichnis befinden sich alle Quelldateien, Bilder und Fonts. Der <code>tasks/</code> Ordner enthält Javascript-Dateien, die die Teilschritte des Build-Prozesses definieren.</p>
<p>Die grobe Struktur sieht folgendermaßen aus:</p>
<pre><code>
├── .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 &#39;Templates&#39;
│   ├── img              // Bilder und Sprites
│   ├── js               // Javascript Quelldateien
│   └── scss             // Sass stylesheets
└── tasks/               // Definitionen für den gulp Build-Prozess
</code></pre>
<h3 id="konventionen">Konventionen</h3>
<p>Die Code Style Konventionen wurden von den ursprünglichen Entwicklern übernommen und nur an wenigen Stellen angepasst. Der Javascript Code ist in ES6 (bzw. ES2015) verfasst und als CSS-Preprocessor wird Sass mit der <code>scss</code> Syntax verwendet.</p>
<p>Das Projekt verwendet <a href="http://editorconfig.org">editorconfig</a> für die Integration dieser Konventionen in Editoren, die entsprechende Datei heißt <code>.editorconfig</code>.</p>
<p>Für die statische Überprüfung des Quellcodes werden folgende <em>Linter</em> verwendet:</p>
<ul>
<li>Javascript: <a href="https://eslint.org">eslint</a></li>
<li>Sass: <a href="https://github.com/sasstools/sass-lint">sass-lint</a></li>
<li>HTML: <a href="https://github.com/htmlhint/HTMLHint">HTMLHint</a></li>
</ul>
<p>Die zugehörigen Konfigurationsdateien befinden sich im Root-Verzeichnis, wie oben in der Auflistung angegeben.</p>
<h2 id="modul-1-risiken-vergleichen">Modul 1: Risiken vergleichen</h2>
<p>Dieses Modul bietet die Möglichkeit, Risiken spielerisch miteinander zu vergleichen. Aus den präsentierten Paaren von Ereignissen muss jeweils dasjenige mit der höheren Eintrittswahrscheinlichkeit gewählt werden. Es wird unmittelbar angezeigt, ob die Schätzung richtig war. Die ‘online’-Version der WebApp zeigt in den folgenden Ansichten, wie man im Vergleich zu anderen Benutzern abschneidet.</p>
<h3 id="javascript-verzeichnisstruktur">Javascript Verzeichnisstruktur</h3>
<p>Für einen besseren Überblick sind die Quell-Dateien mit kurzen Beschreibungen aufgelistet:</p>
<pre><code>├── main.jsx                  // Einstiegspunkt für App *mit* Verwendung der API (&quot;online mode&quot;)
├── main-offline.jsx          // Einstiegspunkt für App *ohne* Verwendung der API (&quot;offline mode&quot;)
├── config.js                 // Globale Konfiguration der WebApp
├── components                // (p)react Komponenten
│   ├── AnswerScreen.jsx
│   ├── FinalScreen.jsx
│   ├── Index.jsx             // Web App Haupt-Komponente
│   ├── QuestionScreen.jsx
│   ├── ScoreScreen.jsx
│   ├── TitleScreen.jsx
│   ├── UserVotesScreen.jsx
│   └── partials
│       ├── AnswerItem.jsx
│       ├── DonutGraphItem.jsx
│       ├── HeaderLightItem.jsx
│       ├── ResponseOptionItem.jsx
│       └── VoteItem.jsx
├── content                   // Definitionen der Inhalte
│   ├── module.json           // Labels und Texte des User Interfaces
│   └── questions.json        // Definitionen der Fragen
├── d3                        // d3 Module
│   ├── axes.js
│   ├── donutchart.js
│   ├── grid.js
│   ├── increment.js
│   ├── legend.js
│   ├── line.js
│   └── symbols.js
└── utilities                 // Werkzeuge und Dienste
    ├── api.js
    ├── enableTouch.js
    ├── fonts.js
    ├── formatter.js
    └── randomizer.js</code></pre>
<h2 id="build-tool-chain">Build Tool Chain</h2>
<p>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.</p>
<h3 id="voraussetzungen">Voraussetzungen</h3>
<p>Dieses Projekt wurde entwickelt auf Basis von [<code>nodejs</code>] unter Verwendung von [<code>npm</code>] als Paket-Manager. Mit den folgenden Versionen wurde zuletzt getestet:</p>
<pre><code>nodejs: v14.4.0
   npm:  6.14.4</code></pre>
<p>Alle Abhängigkeiten sind definiert in der <code>npm</code> Konfigurations-Datei <code>package.json</code>. Wie üblich werden diese installiert mit dem Befehl <code>npm install</code>. [<code>gulp</code>] wird dabei als Task-Manager dieses Projekts global installiert.</p>
<p>Für das Erstellen der Dokumentation aus den einzelnen <em>Markdown</em>-Dateien, die im Verzeichnis <code>doc/</code> liegen, wird <code>[pandoc]</code> verwendet. Dieses ist für viele Betriebssysteme und Distributionen verfügbar, muss aber gesondert installiert werden.</p>
<h3 id="konfiguration">Konfiguration</h3>
<p>Die Build Konfiguration ist in <code>config.js</code> im Wurzelverzeichnis definiert. Außerdem sind in der Datei <code>package.json</code> die zu unterstützenden Browser-Versionen für <code>autoprefixer</code> angegeben.</p>
<p>Konfigurationen für Babel, Editoren und <em>Linter</em> sind ebenfalls im Wurzelverzeichnis zu finden:</p>
<pre><code>       babel: .babelrc
editorconfig: .editorconfig
        html: .htmlhintrc
  javascript: .eslintrc.yml
        sass: .sass-lint.yml</code></pre>
<h3 id="erstellen-von-builds">Erstellen von Builds</h3>
<p>Alle Schritte zum Erstellen von Builds sind in den Javascript-Dateien unter <code>tasks/</code> definiert und werden von der <code>gulp</code> Konfigurationsdatei <code>gulpfile.babel.js</code> importiert. Dort sind die Teilschritte in <em>Tasks</em> zusammengefasst, die man am häufigsten benötigt.</p>
<pre><code>$ gulp        # Default task, Kurzform für &#39;gulp watch&#39;
$ gulp build  # Erstellt einen Development Build
$ gulp watch  # Erstellt einen Development Build und startet den Entwicklungsserver</code></pre>
<h4 id="build-target">Build Target</h4>
<p>Die Unterscheidung zwischen Development und Production Build wird anhand der <code>nodejs</code> Umgebungsvariable <code>NODE_ENV</code> vorgenommen. Ohne diese Angabe wird immer ein Development Build erstellt (siehe <code>config.js</code>). Für das Development Target werden Javascript und CSS zusätzlich mit <em>Sourcemaps</em> versehen, für die Produktiv-Version dagegen werden die Dateien von unnötigem Ballast befreit (<code>terser</code> für Javascript, <code>cssnano</code> für CSS).</p>
<pre><code># Erstellen eines Production Build
$ NODE_ENV=production gulp build</code></pre>
<h4 id="build-mode">Build Mode</h4>
<p>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 <code>config.js</code>).</p>
<pre><code># Erstellen eines Development Build für den &#39;offline&#39; Modus
$ gulp --api-mode=offline</code></pre>
<h4 id="npm-shortcuts">npm Shortcuts</h4>
<p>Da die Handhabung mit dem Setzen der Umgebungsvariable und das Übergeben des Parameters etwas umständlich ist, sind in <code>package.json</code> <code>npm</code> ein paar Shortcuts definiert, z.B.:</p>
<pre><code># Erstellen eines Production Build für den &#39;offline&#39; Modus per gulp Script
$ NODE_ENV=production gulp build --api-mode=offline

# Erstellen eines Production Build für den &#39;offline&#39; Modus per npm Script
$ npm run build:prod:offline</code></pre>
<h3 id="erstellen-der-dokumentation">Erstellen der Dokumentation</h3>
<p>Die Dokumentation in einzelne <em>Markdown</em>-Dateien aufgeteilt, die im Verzeichnis <code>doc/</code> liegen. Zum Erstellen einer zusammenhängender Dokumentation sind folgende <code>npm</code> Scripts definiert, die auf <code>pandoc</code> basieren:</p>
<pre><code>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</code></pre>
<h3 id="konventionen-1">Konventionen</h3>
<p>Der Javascript Code ist in ES6 (bzw. ES2015) verfasst. Als CSS-Preprocessor wird Sass mit der <code>scss</code> Syntax verwendet. Die Code Style Konventionen wurden von den ursprünglichen Entwicklern übernommen und nur an wenigen Stellen leicht angepasst.</p>
<p>Erleichtert wird die Anwendung des definierten Programmierstils durch die Integration in Editoren mit Hilfe von <a href="http://editorconfig.org">editorconfig</a>. Die entsprechende Konfigurationsdatei ist im Wurzelverzeichnis als <code>.editorconfig</code> zu finden.</p>
<p>Die statische Überprüfung des Javascript Quellcodes wird mit Hilfe von <a href="https://eslint.org">eslint</a> durchgeführt.Für Sass wird <a href="https://github.com/sasstools/sass-lint">sass-lint</a> verwendet und HTML wird mit Hilfe von <a href="https://github.com/htmlhint/HTMLHint">HTMLHint</a> überprüft.</p>
<p>Die zugehörigen Konfigurationsdateien befinden sich im Wurzelverzeichnis, wie oben in der Auflistung angegeben. <a href="http://editorconfig.org">editorconfig</a>: http://editorconfig.org <a href="https://eslint.org">eslint</a>: https://eslint.org [gulp]: https://gulpjs.com/ <a href="https://github.com/htmlhint/HTMLHint">HTMLHint</a>: https://github.com/htmlhint/HTMLHint [nodejs]: https://nodejs.org [npm]: https://www.npmjs.com/ [pandoc]: https://pandoc.org <a href="https://github.com/sasstools/sass-lint">sass-lint</a>: https://github.com/sasstools/sass-lint</p>
<h2 id="javascript">Javascript</h2>
<h3 id="verwendete-bibliotheken">Verwendete Bibliotheken</h3>
<p>Die grundlegende Architektur der WebApp wurde implementiert auf Basis von <a href="https://preactjs.com/">preact</a>, von den Entwicklern beworben mit</p>
<blockquote>
<p>Fast 3kB alternative to React with the same modern API.</p>
</blockquote>
<p>Es ist allerdings keine exakte Reimplementierung, weswegen ein eigener Teil der Dokumentation der <a href="https://preactjs.com/guide/v10/differences-to-react">Erläuterung der Unterschiede zu React</a> gewidmet ist.</p>
<p>Für Visualisierungen wird die großartige und weit verbreitete Bibliothek <a href="https://d3js.org/">D3.js</a> verwendet.</p>
<h3 id="verzeichnisstruktur-1">Verzeichnisstruktur</h3>
<p>Die folgende Auflistung gibt einen groben Überblick über die Verzeichnisstruktur der Javascript Quelldateien in <code>src/js/</code>. Als Einstieg dient <code>main.jsx</code> bzw. <code>main-offline.jsx</code> für den “offline” Modus. <code>config.js</code> ist die zentrale Konfigurationsdatei der WebApp. In <code>components</code> liegen die Komponenten der <em>preact</em>-WebApp. Der Quellcode für die D3-Visualisierungen befindet sich unter <code>d3</code>.</p>
<pre><code>├── main.jsx            // Einstiegspunkt für App in &quot;online&quot; Modus
├── main-offline.jsx    // Einstiegspunkt für App in &quot;offline&quot; 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 &quot;offline&quot; Inhalte
├── d3/                 // d3 Module
└── utilities/          // Verzeichnis für Hilfs-Bibliotheken und Werkzeuge</code></pre>
<h2 id="sass">Sass</h2>
<p>Zum Kompilieren von Sass zu CSS wird <code>gulp-sass</code> verwendet, das <code>node-sass</code> benutzt, welches wiederum auf <code>libsass</code> basiert. <code>node-sass</code> hat sich beim wiederholten gedankenlosen Aktualisieren von <code>nodejs</code> und / oder <code>npm</code> als notorischer Nerventöter herausgestellt, daher an dieser Stelle der <a href="https://github.com/sass/node-sass/blob/master/TROUBLESHOOTING.md">Verweis zur <em>Troubleshooting</em> Dokumentation</a> von <code>node-sass</code>. Meist reichte im Falle eines Problems aber ein <code>npm rebuild node-sass</code>.</p>
<h3 id="struktur">Struktur</h3>
<p>In der Datei <code>main.scss</code> werden alle Stile eingebunden, die in den <em>Partials</em> definiert werden, woraus die endgültige CSS-Datei generiert wird. Die Struktur des <code>src/scss</code> Verzeichnisses sieht folgendermaßen aus:</p>
<pre><code>├── base     // Stile für HTML Elemente
├── config   // Globale Variable
├── modules  // Stile für Module
└── tools    // Definierte *mixins* und Funktionen</code></pre>
<h3 id="konventionen-techniken-und-tools">Konventionen, Techniken und Tools</h3>
<p>Generell wird eine “mobile first” Strategie verfolgt. Als Standard-Einheit wird <code>rem</code> 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.</p>
<p>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:</p>
<blockquote>
<p>Hugo Giraudel wrote an awesome piece on everything you need to know about Sass, it’s called <a href="http://sass-guidelin.es/">Sass Guidelines</a> 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 :)</p>
</blockquote>
<p>ʕ̡̢̡ॢ•̫͡ॢ•ʔ̢̡̢</p>
<p>Regeln mit Browser-spezifischen Präfixen (<em>vendor prefixes</em>) werden dem CSS automatisch durch <a href="https://github.com/postcss/autoprefixer">autoprefixer</a> hinzugefügt. Die Liste der zu unterstützenden Browser ist in <code>package.json</code> unter <code>browserslist</code> zu finden.</p>
<h2 id="bilddateien">Bilddateien</h2>
<p>Alle in diesem Projekt verwendeten Bilddateien befinden sich unter <code>src/img/</code>.</p>
<p>Icons in Form von SVG-Dateien befinden sich im Unterordner <code>src/img/sprites</code> und werden im Build-Prozess mittels <code>gulp-svg-sprite</code> zu einem Sprite zusammengefasst. Sie wie folgt in HTML referenziert werden:</p>
<pre><code>&lt;svg class=&quot;icon  icon--arrow-left&quot;&gt;
  &lt;use xlink:href=&quot;assets/img/sprites.svg#icon--arrow-left&quot;/&gt;
&lt;/svg&gt;</code></pre>
<p>Stil-Definitionen für Icons sind unter <code>src/scss/modules/_icons.scss</code> zu finden. Für die Unterstützung von Fragmentbezeichnern (<em>fragment identifier</em>) in Internet Explorer wird <a href="https://github.com/Keyamoon/svgxuse">svgxuse</a> verwendet.</p>
</body>
</html>