# Sampling WebApp

Diese WebApp in Gestalt einer interaktiven Faktenbox soll Verbrauchern ein Verständnis für die Eintrittswahrscheinlichkeit unsicherer Ereignisse vermitteln.


## Abhängigkeiten

Dieses Projekt basiert auf nodejs und npm. Alle Abhängigkeiten sind wie üblich in `package.json` definiert. Die wesentlichen Bibliotheken sind [riot] als WebApp Framework mit webcomponents und [d3js] für die Visualisierung der *Icon Arrays*. [whatwg-fetch] wird als `fetch` *Polyfill* verwendet, um beim Generieren des PDF Resourcen dynamisch zu laden.

## Struktur

Um einen Überblick zu geben, ist hier eine vereinfachte Darstellung der Ordnerstruktur mit kurzen Beschreibungen der wichtigsten Dateien aufgebäumt:

```
├── config.json                         // Preprocess Build Konfiguration
├── rollup.config.js                    // Rollup Build Konfiguration
├── assets
│   ├── js …                            // Externe Bibliotheken für das Generieren von PDFs
│   ├── fonts …                         // Font-Dateien
│   ├── img …                           // Bilddateien (Logos) der umgebenden HTML Seite
├── bin
│   └── preprocess.js                   // Generieren von HTML, JSON und riot Dateien
├── data
│   ├── data.tsv                        // Definition der Daten
│   ├── raw
│   │   └── RA_ExpFB_Renditedaten.xlsx  // Rohdaten
│   └── sampling-info.md                // Inhalt des Info-Textes der WebApp
└── src
    ├── css
        └── styles.css                  // Layout und Styling der WebApp
    └── html
    │   └── main.html                   // Gerüst für HTML Datei
    └── js
        ├── components                  // Web components
        │   ├── config_visual.json      // Konfiguration für die Visualisierungs-Komponente
        │   ├── sampler-controls.riot   // Komponente für die Formularelemente eines Samplers
        │   ├── [sampler-info.riot]     // Aus `data/sampling-info.md` generierte Komponente für zusätzliche Informationen
        │   ├── sampler-textual.riot    // Komponente für die textuelle Representation
        │   ├── sampler-visual.riot     // Komponente für die Visualisierung (Icon Array)
        │   ├── sampling-app.riot       // Haupt-Komponente
        │   └── sampling-header.riot    // Komponente für den Header mit Formularelementen und Info-Button
        ├── d3custom.js                 // Sammlung der verwendeten d3js module
        ├── main.js                     // Einstieg für riot-App
        ├── options.json                // Konfiguration der WebApp
        ├── pdfExport.js                // Erstellung des PDF-Datei (Faktenbox)
        └── sampler.js                  // Implementierung des Samplings

```

## Build Prozess

Alles Scripts des Build Prozesses sind in der `package.json` definiert:

     "scripts": {
        "prepare": "npm run build",
        "build": "npm run build:preprocess && npm run build:once",
        "build:preprocess": "node bin/preprocess.js",
        "build:once": "rollup -c",
        "build:dev": "NODE_ENV=development npm run build",
        "build:prod": "NODE_ENV=production npm run build",
        "watch": "NODE_ENV=development npm run build:preprocess && NODE_OPT=serve rollup -c --watch"
      }, …

Die Unterscheidung, ob ein *development* oder *production* Build erstellt werden soll, wird anhand der Umgebungsvariable `NODE_ENV` getroffen.
Eine nicht ganz so standardkonforme Variable `NODE_OPT` wird benutzt, um feststellen zu können, ob der Entwicklungsserver gestartet werden soll.

Der Build Prozess ist zweistufig und daher etwas komplex, da temporäre Dateien generiert werden, um das Ändern von Inhalten möglichst einfach zu halten.

### Erstellen von temporären Dateien

Im *Task* `build:preprocess` werden mit Hilfe eines nodejs Scripts in einem Zwischenschritt aus den *Markdown*-Dateien unter `data` Dateien generiert, die im npm Build Prozess verwendbar sind:

- Aus `src/html/main.html` wird die HTML-Datei `dist/index.html` generiert, die vom Web Server ausgeliefert wird.
- Aus `data/sampling-info.md` werden die Komponente `dist/data/sampling-info.riot` für die interaktive Visualisierung und die JSON-Datei `dist/data/sampling-info.json` zur Verwendung beim Erstellen des PDFs generiert.

### Erstellen der eigentlichen WebApp

Der *Task* `build:watch` ist geeignet für die Entwicklung, da geänderter Code sofort neu *transpiliert* und die WebApp vom Entwicklungsserver neu geladen wird.
Für die Erzeugung eines *Production Build* ist das Script `build:prod` zuständig.

In `rollup.config.js` ist der eigentliche Build Prozess definiert. Das Script *transpiliert* ES2015 Javascript und riot-Dateien und kopiert Ressourcen aus `assets/` nach `dist/`. Dies ist auch das Verzeichnis, dass der Entwicklungsserver ausliefert. 

### Konfiguration

Die Konfiguration des Build Prozesses ist in `config.json` zu finden. Dort sind Namen und Namensfragmente der Verzeichnisse und Dateien angegeben, aber auch die Dimension des zu erzeugenden *iframes*.

### Deployment

Nach einem Production Build kann `dist/` als statisches HTML-Verzeichnis von einem Webserver ausgeliefert werden.

## Wie ändere ich Inhalte und Daten?

### Labels und Texte

Die meisten Texte und Textfragmente sind definiert in `src/options.json`. Dort können Titel und Labels der Buttons angepasst werden.
Der Text, der beim Klick auf den Info-Button erscheint, ist in `data/sampling-info.md` zu finden. Aus dieser Datei werden im *Preprocess* Schritt temporäre Dateien erzeugt (`riot` für die interaktive Ansicht und `json` für das Generieren des PDF). Im eigentlichen Build Prozess werden diese in die WebApp integriert.

### Daten

Die Rohdaten sind in `data/data.tsv` enthalten. In `src/options.json` sind die Auswahloptionen im Objekt `investmentOptions` festgelegt. Hier sind auch die Standard-Werte der Zielvorgaben definiert:

```
"investment": {
    "input": {
        "value": 1000,
            "min": 1,
            "max": 1000000
    },
        "output": {
            "value": 2000,
            "min": 1,
            "max": 1000000
        },
        "options": [
            { "id": 0, "name": "dax", "desc": "Aktien DE (Dax)"   },
            { "id": 1, "name": "gol", "desc": "Gold UK"           },
            { "id": 2, "name": "fts", "desc": "Aktien DE (allg.)" },
            { "id": 3, "name": "bon", "desc": "Bundesanleihen DE" },
            { "id": 4, "name": "fes", "desc": "Festgeld DE"       },
            { "id": 5, "name": "sp",  "desc": "Aktien USA (S&P)"  },
            { "id": 6, "name": "msci",  "desc": "MSCI World"  }
        ]
},
```

[d3js]: https://d3js.org
[riot]: https://riot.js.org
[whatwg-fetch]: https://github.com/github/fetch
