experience-based-fact-box

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"  }
        ]
},