Skip to content

wdr-data/quiz-ki

Folders and files

NameName
Last commit message
Last commit date

Latest commit

5662d12 · Mar 25, 2024
Oct 12, 2022
Apr 25, 2023
Apr 25, 2023
Mar 25, 2024
Apr 25, 2023
Feb 4, 2022
Apr 25, 2023
Oct 12, 2022
Apr 5, 2023
Jul 16, 2019
Sep 21, 2020
Oct 12, 2022
Oct 12, 2022
Oct 12, 2022
Jun 28, 2019
Apr 25, 2023
Apr 25, 2023
Apr 25, 2023

Repository files navigation

starter

Der WDR-Data Starter ermöglicht es JournalistInnen, unsere Design-Patterns und die Komponentenbibliothek für datengesteuerte Journalismusprojekte zu nutzen.

Ziele:

  • Einen abgenommenen Rahmen haben, in dem Datenprojekte schneller stattfinden können
  • Neue Visualisierungsformen mobile first und accessible erproben
  • Entwicklungen wiederverwendbar machen (Als Datengeschichte auf data.wdr.de und als Grafik-iFrame im CMS)

Für JournalistInnen

Wie nehme ich ein Datenprojekt ab?

  • Ersteller*in schickt Link zu:

    • Preview bei Netlify - z.B.: http://data-wdr.netlify.com/oper-in-nrw
    • Markdown-File dazu in Github - z.B.: https://github.com/wdr-data/starter/pages/index.md
  • Zum Bearbeiten:

    • Auf Stift-Icon oben rechts: Edit this File
    • Änderungen vornehmen / Preview ansehen
    • Zum Abschluss unten unter 'Commit changes' die Änderung dokumentieren
    • Auf 'commit changes' klicken
  • Commit löst aus:

    • Änderungen werden dokumentiert (und sind rückgängig zu machen)
    • Änderungen werden im Slack gepostet
    • Automatische Veröffentlichung der Änderung bei Netlify

Wie lege ich ein neues Datenprojekt an? (Alternativ Datenteam darum bitten)

🌐 https://github.com/wdr-data/starter/

  • Für den Zugang ist ein Github Account nötig

Schritte:

  1. Ein neues, leeres Repo unter data.wdr.de anlegen
  • Projekte können wahlweise von Anfang an 'öffentlich' sein oder erst später veröffentlicht werden
  1. git clone <new repository>.git des neuen Repos auf dem eigenen Rechner
  2. In das neue Verzeichnis wechseln: cd <new repository>
  3. Die Referenz zum starter Repository hinzufügen: git remote add upstream https://github.com/wdr-data/starter.git
  4. Alle Inhalte aus dem Starter ins neue Verzeichnis ziehen: git pull upstream main
  5. Alle Inhalte zum neuen Verzeichnis pushen: git push origin master

Mit Netlify verbinden

➡️ Netlify.com Eigenen kostenlosen Account anlegen oder WDR Data fragen

  • New site from git
  • Github auswählen
  • Ggf. mit Github verbinden / authentifizieren (nur einmal nötig)
  • Repo auswählen
  • Branch to deploy: master
  • Build command: yarn build
  • Publish directory: public
  • Ggf. unter Site Details: Change site name

Mit Slack verbinden (optional)

  • ggf. neuen Channel für das Projekt anlegen
  • /github subscribe wdr-data/ddj-test

Meine Story bearbeiten

Unter /pages die index.md mit eigenen Inhalten überschreiben:

Metadatenfelder für SEO, Twitter-Cards, Facebook Open-Graph

---
title: "Opern-Spielpläne in NRW: tot und männlich"
description: WDR 3 Datenanalyse der Opern-Spielzeit 2018/2019
author: Niklas Rudolph, Patricia Ennenbach
pub_date: "2019-07-15"
heroImage: "richard-wagner-und-freunde.jpg"
heroAlt: "Richard Wagner und seine Freunde"
heroCredit: "Richard Wagner und seine Freunde"
sharingImageFacebook: "richard-wagner-und-freunde_facebook.jpg"
sharingImageTwitter: "richard-wagner-und-freunde_twitter.jpg"
cg1: "WDR"
cg2: "Data"
cg3: "WDR 3"
cg4: "Opern-Spielpläne in NRW: tot und männlich"
---
  • title - Überschrift

  • description - Beschreibung

    • für das Google-Suchergebnis
    • ca. 160 Zeichen
  • author - Liste der AutorInnen

    • als Liste (Spiegelstriche, eingerückt)
  • pub_date - Veröffentlichungsdatum

    • z.B. 2019-06-27
  • heroImage - Titelbild

  • heroAlt - Alt-Attribut für Titelbild

  • heroCredit - Credit für Titelbild

  • sharingImageFacebook: - Bild für Faceook open graph

  • sharingImageTwitter: - Bild für Twitter card

  • Die Bilder für Facebook und Twitter werden in static/ abgelegt

Webtrekk

Im Kopf der src/pages/index.md:

  • ! pub_date: "2019-07-15" muss in diesem Datums-Format vorhanden sein
  • Anhand dieses Schemas ausfüllen:
    • cg1: "WDR"
    • cg2: "Data"
    • cg3: "WDR 3" - Partnerredaktion
    • cg4: "Opern-Spielpläne in NRW: tot und männlich" - H1 (Hauptüberschrift) des Stücks
  • Optional kann auch eine cg5: vergeben werden

Sharing

Die Inhalte der Komponente werden auch im Kopf der index.md festgelegt:

Texte in Markdown

Die eigentliche Geschichte wird in Markdown geschrieben, das ist eine vereinfachte Auszeichnungssprache fürs Web.

💡 Markdown Cheat Sheet

Bilder

  • Unter /static werden die Bilddateien für das Projekt abgelegt (HeroImage, weitere Bilder)

heroImage: 1920x1080 Sophora / Full HD Twitter: 2:1 - mindestens 300 x 157 Facebook: 1200 x 630

Weitere Bilder:

  • 1920x1080 Sophora / Full HD

Bild einfügen:

<figure role="group">
<img src="berthold-schneider-credit-jens-grossmann.jpg" alt="Der Wuppertaler Opernintendant Berthold Schneider, fotografiert von Jens Grossmann" />
<figcaption style="text-align: end;">Berthold Schneider</figcaption>
</figure>

Weitere Komponenten in Markdown einbinden

Es können Komponenten aus der Bibliothek unter wdr-data.netlify.com/components eingebunden werden. Dazu wird die Markdown-Erweiterung MDX verwendet.

Um Komponeneten nutzen zu können, müssen sie in der index.md importiert werden. Laut Konvention oben unter den Metadaten.

import DataWrapper from '../components/datawrapper/datawrapper.jsx'
import Quote from '../components/quote/quote.jsx'
import Accordion from '../components/accordion/accordion.jsx'
import Webtrekk from '../components/webtrekk/webtrekk.jsx'
import Sharing from '../components/sharing/sharing.jsx'

Datawrapper

Beim Grafiken bauen beachten

  • Design: Datawrapper
  • Titel ausblenden, Subtitle weglassen (passiert im Markdown des Projekts)
  • Datenquelle, Link zur Datenquelle und Verfasserzeile ausfüllen
  • Social Media Sharing aus
  • Farbskala anpassen: Für unterschiedliche Graphentypen stehen Möglichkeiten der farblichen Modifizierbarkeit zur Verfügung. Beispielhaft folgen zwei Optionen.
  1. Farben > importieren #dadfdf,#b6cad1,#5bb1c0,#365886,#1d2124

  2. Farbwerte ersetzen: #1D2124 (WDR Dunkelblau) #00345E (WDR Blau) #007381 (WDR Petrol) #B37500 (WDR Honiggelb)

Fertige Grafik veröffentlichen und Datawrapper-Pfad kopieren: //datawrapper.dwcdn.net/6D2bM/4/

Maps und Charts einbinden

Um eine im Datawrapper erstellte Grafik einzubinden, wird in den Fließtext folgendes eingebaut:

### Jeder dritte Komponist lebt - wird aber kaum aufgeführt

<figure role="group">
    <figcaption> Bei Klick auf 'KomponistInnen' ist zu sehen, wie das Verhältnis von verstorbenen zu lebenden KomponistInnen ist.</ figcaption>
    <DataWrapper
        alt="Fast jede dritte KomponistIn lebt, aber nur 9 % der Aufführung stammen von ihnen."
        title="Nur 9 % der Aufführungen stammen von lebenden KomponistInnen."
        src="//datawrapper.dwcdn.net/6D2bM/4/"
    />

</figure>
  • H3-Überschrift der Grafik - möglichst sprechend: So what? Was ist die Erkenntnis?
  • Figcaption: Erklärung der Grafik, was ist zu sehen? Was kann wie angeklickt werden?
  • alt: Alternativ-Text: Textlichte Beschreibung des Inhalts
  • title: Wird aus der H3-Überschrift der Grafik übernommen
  • scr: Datawrapper-Pfad einfügen

Quote

Zitat mit Nennung des Urhebers, Verlinkung möglich.

Ohne Link:

<Quote author="Berthold Schneider, Intendant Oper Wuppertal">Die Oper ist stark genug, dass sie sich immer wieder verändern wird.</Quote>

Mit Link:

<Quote author={
<a href="https://blogs.nmz.de/badblog/2018/04/10/die-ernuechternde-opernstatistik-der-spielzeit-2017-2018/" target="_blank" rel="noopener noreferrer">Moritz Eggert</a>
}>Überlebenschance der Gattung Oper, wenn sich nicht grundlegend etwas ändert: 0%</Quote>

Accordion

Data

  • unter /data werden Daten (.csv, .json etc.) und Datenanalyse-Notebook abgelegt

Für DesignerInnen

Typografie

Im Design greifen wir auf die u.g. Schriften zurück:

Eine Übersicht zur Typografie befindet sich hier: https://wdr-data.netlify.com/components/?path=/story/typography--default

Farben

Die Farbkontraste für das gesamte Design sind im Kontrast Checker überprüft worden.

  • Schriftfarbe: #1D2124 (WDR Dunkelblau)
  • Flächenfarbe: #00345E (WDR Blau)
  • Highlightfarbe für Links: #007381 (WDR Petrol)
  • Akzentfarbe: #B37500 (WDR Honiggelb)

Logo & Header

Im oberen Bereich einer jeden Dataseite befindet sich lediglich das WDR Logo, mithilfe dessen man aus der Datawelt zurück in die WDR Welt navigieren kann.

  • Falls ein Hero Image vorhanden ist: Weißes WDR Logo im Rechteck auf Blau
  • Falls kein Hero Image vorhanden ist: Blaues WDR Logo auf weiß

Iconography

https://icomoon.io/#preview-free

Designprinzipien

  • Arbeite mit einfach erkennbaren visuellen Hierachien
  • Nutze ein klar strukturiertes Layout ohne Ablenkungen mit Fokus auf Inhalten
  • Erschaffe ein konsistentes Design mit modular einsetzbaren und wiederkehrenden Elementen
  • Gestalte ein leichtes, modernes und ansprechendes Design mit Mut zu Weißraum

Sketch files

ToDo: Sketch Datei hinterlegen

Für EntwicklerInnen

  • Pull-Request stellen oder per Mail / bei Github darum bitten, Teil des Teams zu werden: [email protected]

Repository: https://github.com/wdr-data/starter

Wie entwickle ich lokal?

Voraussetzungen:

  • Git installieren
  • Code Editor (z.B. VS Code installieren)
  • Node installieren
  • Yarn installieren

Entwicklung:

  • Falls noch nicht geschehen:
    • Lese- und Schreibrechte auf dem Repository erlangen
    • git clone <repo-clone-url> kopiert das Projekt auf den eigenen Rechner
  • Änderungen machen in src/pages/index.md
    • Änderungen speichern
  • Um das Projekt zu lokal zu starten: yarn start (Solange das läuft, werden gespeicherte Änderungen automatisch erkannt und die Seite neu kompiliert)
  • Um die Änderungen zu dokumentieren und zu veröffentlichen:
git status
git add src/pages/index.md
git commit -m ":bento: Grund für die Änderung"
git status (Alles grün?)
git push

🌐 Git cheat sheet

Wie baue ich eine neue Komponente?

Komponenten liegen im Git Repo unter src/components. Jede Komponente hat einen eigenen Unterordner mit folgenden Dateien:

  • JSX-Datei - React-Code der Komponente
  • CSS-Datei - Styling
  • .stories.jsx - Enthält die Stories für das Storybook

Wie integriere ich React Komponenten?

Am Beispiel Semiotic

  • Neuen Branch anlegen feature/semiotic
  • yarn add xy
  • Unterordner für die Komponente anlegen
  • JSX, CSS und stories.jsx Datei anlegen

Guides / Manuals für React

Storybook

💡 Storybook Dokumentation

Eine lebende Dokumentation der Komponentenbibliothek. Hier kann jede Komponente in ihren Ausprägungen angesehen und ausprobiert werden.

➡️ Starter-Komponenten (unser Storybook)

Das Ziel ist die Funktion der Komponente greifbar zu machen. Dazu können entweder mehrere Stories pro Komponente erstellt oder Knobs benutzt werden.

ToDo: Screenshot hinzufügen

Gatsby: Publishing-Umgebung

Der Starter nutzt Gatsby zum Generieren von statischen HTML-Seiten aus unserem Basis-Layout und Markdown-Inhalten.

Das Gatsby-Setup wurde auf Basis des Schnellstart-Tutorial aufgebaut.

Ein Großteil der Konfiguration von Gatsby befindet sich in gatsby-config.js.

Relevante Ordner für Gatsby

  • src/pages
    • Ablage für statische Inhaltsseiten
    • 💡 Gatsby: Mit Seiten arbeiten
    • aus jeder JS(X)-Datei wird eine statische Seite generiert
    • der Dateiname dient als URL
    • index.md wird zur Startseite
  • src/templates

Wie wird Markdown zu HTML?

💡 Tipp: GraphQL-Playground unter http://localhost:8000/__graphql benutzen

Wenn ich yarn start oder yarn gatsby build ausführe werden folgende Schritte ausgeführt:

  1. Einlesen der Markdown-Dateien als Gatsby-Nodes
    • via gatsby-source-filesystem
    • Das Plugin gatsby-source-filesystem liest alle Dateien im Ordner content ein
    • Erstellt werden Nodes vom Typ File
    • Beispiel-Query:
      query MyQuery {
        allFile {
          edges {
            node {
              name
              extension
            }
          }
        }
      }
  2. Parsen der Dateien in MDX-Nodes
    • via gatsby-plugin-mdx
    • Nimmt alle File-Nodes mit Extension md oder mdx
    • Wandelt Markdown zu JSX
    • Macht Frontmatter in Gatsby verfügbar
    • Erstellt Nodes vom Typ MDX
    • Beispiel-Query:
      query MyQuery {
        allMdx {
          nodes {
            frontmatter {
              title
              author
              description
              pub_date
              slug
            }
            rawBody
          }
        }
      }
  3. Erstellen von Gatsby Pages
    • Custom Code in gatsby-node.js
    • Weist eine URL aus slug zu oder macht title URL-fähig (TODO)
    • Weist der Seite ein Template zu
  4. Generieren der statischen Seiten aus Inhalt und Template
    • Ausführen der GraphQL-Query im zugewiesenen Template-File
      • Query in Named Export pageQuery
      • context aus createPage dient als Parameter der Query (z.B. $id)
    • Rendern der Template-Komponente
      • Komponente als Default Export
      • Ergebnis der GraphQL wird als data Property gesetzt
Inhalte als Markdown
  • pages/index.md
    • Ablage für Datengeschichten
    • pro Geschichte ein repo mit einer eine Markdown-Datei
    • Die MDX-Erweiterung wird genutzt um inline Komponenten einsetzen zu können
    • 💡 Gatsby and MDX

Über Seiten-Templates

💡 Gatsby: Templates für MDX-Seiten

Was ein Template machen sollte:

  • Header einbinden
  • Markdown-Inhalt einheitlich stylen
  • Meta-Tags für die Seite setzen
  • Breadcrumb erstellen
  • Footer einbinden

Plugins

Genutzte Plugins:

  • Source Filesystem
    • Einlesen der Inhalte als Gatsby-Nodes zur Weiterverarbeitung
  • MDX Plugin
    • Parsing von MDX-Dateien zu Gatsby Pages
    • Genutzte Extensions: md & mdx
    • Ziel: Verarbeiten von Seiten aus dem Filesystem-Plugin
  • Remark Images
    • Extrahiert Bilder, die in Markdown referenziert werden
    • Wichtig: Es können nur Bilder aus dem gleichen Ordner referenziert werden
  • Sharp
    • Skaliert verwendete Bilder in verschiedene Größen
  • React Helmet Plugin
    • fügt Metadaten dem <head> hinzu
    • React Helmet kann aus jeder Komponente zum Setzen von Metadaten genutzt werden
    • Globale Metadaten werden in der Komponente SEO verwaltet
  • Manifest Plugin
    • Erzeugt ein PWA-Manifest

TODO: Erklären

Code-Style

TODO

Deployment

Der DDJ-Editor wird bei Netlify gebaut & gehostet. (PBI-Kreditkarte hinterlegt.)

Was passiert?

  • Push ins Git-Repository
  • Netlify CI baut das Projekt automatisiert
  • Bereitstellung des Build-Outputs auf dem Netlify CDN (bei erfolgreichem Build)

Warum?

  • Nachvollziehbarer Output basierend auf einer automatisierten Umgebung
  • Klare Verknüpfung zwischen Git-Commit und veröffentlichtem Ergebnis

CI & Hosting

Konfiguration ist definiert in netlify.toml. Sie überschreibt die Einstellungen, die man im Netlify-UI vornimmt.

➡️ netlify.toml Docs

Die Netlify Build-Umgebung geht so vor:

  • Installieren der Dependencies (yarn)
  • Ausführen des Build-Kommandos
  • Hochladen des Ergebnis ins CDN

Automatisch von der CI-Umgebung gebaut werden Main-Branch und alle Pull-Requests. Netlify stellt für Pull Requests sog. "Preview Builds" bereit, die eine LIVE-Vorschau von Änderungen unter einer URL ermöglicht.

/public dient als Deployment-Ordner und wird von Netlify nach erfolgreichem Build aus der CI im CDN veröffentlicht.

Das zentrale Build-Kommando (yarn build) baut 3 Teile:

Storybook

  • Befehl: yarn build-storybook
    • Build-Tooling: npm-Modul storybook
    • Konfiguriert in .storybook
  • Ergebnis liegt in: public/components
  • Ergebnis URL-Pfad /components

Publikation

  • im URL-Pfad: /
  • Befehl: yarn build-gatsby
    • Build-Tooling: Gatsby
  • Ergebnis liegt in: public

Auf data.wdr.de

Per Mail an Dittmann um neuen Ordner auf data.wdr.de bitten. Mit den Zugangsdaten Daten aus dem Build-Ordner auf den Server hochladen.

Tests

TODO

Visual Regression Testing

Accessability testing

Content checks

  • Dead links
  • Missing URLs