Repository files navigation

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)

• 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

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

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

Schritte:

• Für eine neue Story:globe_with_meridians:How To Fork Your Own GitHub Repository

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

2. git clone <new repository>.git des neuen Repos auf dem eigenen Rechner
3. In das neue Verzeichnis wechseln:cd <new repository>
4. Die Referenz zumstarter Repository hinzufügen:git remote add upstream https://github.com/wdr-data/starter.git
5. Alle Inhalte aus dem Starter ins neue Verzeichnis ziehen:git pull upstream main
6. Alle Inhalte zum neuen Verzeichnis pushen:git push origin master

➡️Netlify.comEigenen 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

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

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

---title: "Opern-Spielpläne in NRW: tot und männlich"description: WDR 3 Datenanalyse der Opern-Spielzeit 2018/2019author: Niklas Rudolph, Patricia Ennenbachpub_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

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 einecg5: vergeben werden

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

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

💡Markdown Cheat Sheet

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

heroImage: 1920x1080 Sophora / Full HDTwitter: 2:1 - mindestens 300 x 157Facebook: 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>Berthold Schneider</figcaption></figure>

Es können Komponenten aus der Bibliothek unter wdr-data.netlify.com/components eingebunden werden. Dazu wird die Markdown-ErweiterungMDX 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'

• 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/

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

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/" rel="noopener noreferrer">Moritz Eggert</a>}>Überlebenschance der Gattung Oper, wenn sich nicht grundlegend etwas ändert: 0%</Quote>

• Die Inhalte liegen als einzelne .md Dateien in /accordion
• Um Inhalte zu ändern, wird die entsprechende .md Datei geändert:authors.mdcredits.mdhints.mdsources.md

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

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

• Google FontMerriweather in Regular 400
• Google FontOpen Sans in Light 300 und Semibold 600

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

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

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

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ß

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

• 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

ToDo: Sketch Datei hinterlegen

• Pull-Request stellen oder per Mail / bei Github darum bitten, Teil des Teams zu werden:wdr-data@hacking.studio

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

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

• 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 insrc/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 statusgit add src/pages/index.mdgit commit -m ":bento: Grund für die Änderung"git status (Alles grün?)git push

🌐Git cheat sheet

Komponenten liegen im Git Repo untersrc/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

Am BeispielSemiotic

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

• https://reacttraining.com/blog/javascript-the-react-parts/
• https://reactjs.org/tutorial/tutorial.html
• https://leanpub.com/the-road-to-learn-react/
• https://reactpatterns.com/
• https://www.learnstorybook.com/react/en/simple-component/
• https://reactjs.org/docs/faq-styling.html
• https://github.com/css-modules/css-modules/blob/master/README.md

💡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 oderKnobs benutzt werden.

ToDo: Screenshot hinzufügen

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

Das Gatsby-Setup wurde auf Basis desSchnellstart-Tutorial aufgebaut.

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

• 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
  • Ablage für Seitenvorlagen
  • 💡Gatsby: Seiten generieren
  • enthältdefault.jsx - bestimmt Grundlayout und Metadaten

💡Tipp: GraphQL-Playground unterhttp://localhost:8000/__graphql benutzen

Wenn ichyarn start oderyarn gatsby build ausführe werden folgende Schritte ausgeführt:

1. Einlesen der Markdown-Dateien als Gatsby-Nodes
   • viagatsby-source-filesystem
   • Das Plugingatsby-source-filesystem liest alle Dateien im Ordnercontent ein
   • Erstellt werden Nodes vom TypFile
   • Beispiel-Query:

     queryMyQuery {allFile {edges {node {nameextension      }    }  }}

2. Parsen der Dateien in MDX-Nodes
   • viagatsby-plugin-mdx
   • Nimmt alle File-Nodes mit Extensionmd odermdx
   • Wandelt Markdown zu JSX
   • Macht Frontmatter in Gatsby verfügbar
   • Erstellt Nodes vom TypMDX
   • Beispiel-Query:

     queryMyQuery {allMdx {nodes {frontmatter {titleauthordescriptionpub_dateslug      }rawBody    }  }}

3. Erstellen von Gatsby Pages
   • Custom Code ingatsby-node.js
   • Weist eine URL ausslug zu oder machttitle URL-fähig (TODO)
   • Weist der Seite einTemplate zu
4. Generieren der statischen Seiten aus Inhalt und Template
   • Ausführen der GraphQL-Query im zugewiesenen Template-File
     • Query in Named ExportpageQuery
     • context auscreatePage dient als Parameter der Query (z.B.$id)
   • Rendern der Template-Komponente
     • Komponente als Default Export
     • Ergebnis der GraphQL wird alsdata Property gesetzt

• pages/index.md
  • Ablage für Datengeschichten
  • pro Geschichte ein repo mit einer eine Markdown-Datei
  • DieMDX-Erweiterung wird genutzt um inline Komponenten einsetzen zu können
  • 💡Gatsby and MDX

💡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

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 KomponenteSEO verwaltet
• Manifest Plugin
  • Erzeugt ein PWA-Manifest

TODO: Erklären

• CSS Modules
• SEO
• Google Analytics

TODO

Der DDJ-Editor wird beiNetlify 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

Konfiguration ist definiert innetlify.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:

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

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

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

TODO

• Snapshot:https://www.npmjs.com/package/@storybook/addon-storyshots-puppeteer
• Compare:https://github.com/reg-viz/reg-cli

• https://github.com/dequelabs/axe-core
• https://github.com/dequelabs/react-axe
• https://developers.google.com/web/tools/lighthouse/

• Dead links
• Missing URLs