27_Anlage_2_Technische_Dokumentation_final.pdf

Technische Dokumentation

Frontend XX – Bundesarchiv

Stand: 21.06.2023

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

Inhaltsverzeichnis

1 Vorbemerkung ...................................................................................................................... 3 1.1 Anlagen............................................................................................................................... 3

API-Schnittstelle Frontend-Backend und Datenübergabe ...................................................... 4 1.2 Ausgangslage ..................................................................................................................... 4 1.2.1 Abgrenzung zwischen Frontend und Backend .............................................................................. 4 1.2. 2 Anforderungen an XML ................................................................................................................. 5 1.2.3 Bildausgabe .................................................................................................................................. 5 1.2.4 Beispiel-Rückgabe des Backends ................................................................................................. 5 1.2.5 Anforderungen an die Bilder ......................................................................................................... 5 1.3 Weitere Anforderungen für verschiedene Leistungsbestandteile....................................... 6 1.3.1 Anforderungen an die Suche ........................................................................................................ 6 1.3. 2 Pflege Statischer Labels ............................................................................................................... 6

2 Frontend-Konzept ................................................................................................................ 7 2.1 Einleitung ............................................................................................................................ 7 2. 2 Nutzerführung ..................................................................................................................... 7 2.3 Technology Stack ............................................................................................................. 10 2.3. 1 Build-Prozess .............................................................................................................................. 10 2.3. 2 Basistechnologie ......................................................................................................................... 10 2.3.3 Versionierung .............................................................................................................................. 10 2.3.4 Qualitätssicherung ...................................................................................................................... 10 2.3.5 Innerhalb des ausgelieferten Codes verwendete Frameworks und Libraries .............................. 11 2.3.6 XML Parser ................................................................................................................................. 11 2.4 Abnahmesysteme ............................................................................................................. 11 2.5 Designumsetzung ............................................................................................................. 12 2.5. 1 Responsive-Design ..................................................................................................................... 12 2.5. 2 Atomic Design ............................................................................................................................. 13 2.5.3 Theming ...................................................................................................................................... 13 2.5.4 Komponentensystem und Templating ......................................................................................... 13 2.6 Gestaltungskonzept .......................................................................................................... 13 2.6.1 Standardschriften ........................................................................................................................ 13 2.6. 2 Farben ......................................................................................................................................... 14 2.6.3 SVG-Icons ................................................................................................................................... 14 2.7 Patternlibrary .................................................................................................................... 14 2.8 Performance ..................................................................................................................... 14

3 Barrierefreiheit ................................................................................................................... 15 3.1 Sonstige Optimierungen ................................................................................................... 15 3. 1.1 Favicon ....................................................................................................................................... 15 3.1. 2 SEO ............................................................................................................................................ 15 3.1.3 Druckversion ............................................................................................................................... 15

4 Git-Workflow ....................................................................................................................... 17 4.1 Seiten-URLs ..................................................................................................................... 18 4. 1.1 Hauptseiten ................................................................................................................................. 18 4.1. 2 Statische / Unterseiten ................................................................................................................ 19 4.2 Installationsanleitung inkl. Abhängigkeiten....................................................................... 20 4.3 Betriebskonzept ................................................................................................................ 20 4.3. 1 Einleitung .................................................................................................................................... 20 4.3. 2 Development ............................................................................................................................... 20 4.3.3 Staging ........................................................................................................................................ 21 4.3.4 Production ................................................................................................................................... 21 4.4 Abnahmeplan ................................................................................................................... 22

Table of Contents – 2

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

1 Vorbemerkung

Basierend auf Vertrag Nr. B12.12 – 0094/21/VV: 1 und der zugrundeliegende Leistungsbeschreibung wurde folgende technische Dokumentation erstellt.

Die Umsetzung weicht von dem im Feinkonzept abgenommen Design ab, wenn sich Anforderungen während der Entwicklung geändert haben.

Entsprechende Änderungen wurden in den jeweiligen Story-Tickets dokumentiert.

1.1 Anlagen

Die technische Dokumentation gilt in Zusammenhang mit folgenden Dokumenten: • Export_API_Dokumentation_Bundesarchiv.zip • Bundesarchiv-Angular-Projekt.zip (inkl. Sourcecode) • Patternlibraby-storybook-static.zip • BARCHIV_Testkonzept (u.a. für Responsive-Stufen und Abnahmesysteme)

3

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

API-Schnittstelle Frontend-Backend und

Datenübergabe

1.2 Ausgangslage

Das Frontend wird mit Hilfe des Angular Frameworks umgesetzt. Hierfür wird eine im Framework verwendete Templating Engine verwendet. Diese ermöglicht die Erstellung dynamischer und anpassbarer Benutzeroberflächen in Form eines Komponenten-Systems. So entsteht eine klare Trennung zwischen Front- und Backend. In diesem Dokument werden wir uns auf die Verwendung des Frameworks und die Integration der vom Backend bereitgestellten Daten konzentrieren.

Um die Daten aus dem Backend im Frontend verwenden zu können, werden diese über die API-Schnittstelle des Backendsystems angefragt. Diese Daten können im JSON oder auch im XML-Format vorliegen.

Mithilfe des Frameworks und der API-Dokumentation werden AJAX-Anfragen erstellt und an die API gesendet.

Integration von Daten in das Frontend:

Sollten diese Daten im JSON-Format vorliegen, werden diese entgegengenommen und die einzelnen JSON Objekte und deren Typen auf die jeweiligen Angular-Komponenten, dessen Attribute abgebildet und letztendlich dargestellt.

Liegen die Daten im XML-Format vor, wird die XML Struktur mithilfe eines eigens entwickelten Parsers (siehe Punkt 3.3.6) aufgeteilt und in geeignete HTML-Elemente oder Angular- Komponenten umgewandelt. Dies ist notwendig, da im XML andere Tags verwendet werden als im HTML-Kontext. Dabei bleibt der Text im Original-XML erhalten.

Sonderregeln wie Styling-Klassen der XML-Tags werden ebenfalls übernommen und als CSS- Klassen abgebildet. Texte innerhalb des XML-Tags werden ohne Änderungen übernommen. So wird eine eins-zu-eins Referenz geschaffen, um die Daten des Backends mit dem Design zu verbinden.

1.2.1 Abgrenzung zwischen Frontend und Backend

Alle statischen Elemente (HTML-Struktur, Responsive Design, Icons etc.) liegen im Frontend und wurden von XX umgesetzt. Das Frontend kümmert sich darum, die vom Backend erhaltenen Daten dem Nutzer so anzuzeigen, wie es das Design vorsieht. Dabei findet im Frontend keine Businesslogik statt, sondern ausschließlich Logik, um die vom Backend erhaltenen Daten anzuzeigen bzw. Nutzerinteraktionen auszuführen (z.B. das Öffnen eines Popups, wenn der Nutzer einen Button anklickt).

Alle dynamischen Funktionalitäten und Daten (Listenattribute, Inhaltstexte, Bilder, Suchlogik, Paginierung etc.) werden vom Backend geliefert. Außerdem findet hier die Businesslogik statt (wie zum Beispiel das Durchsuchen von Inhalten, Filtern, Paginierungen, etc.). Für solche Anwendungsfälle erhält das Backend nach einer Nutzerinterkation eine Anfrage vom Frontend wie "Gib mir alle Protokolle, zwischen den Jahren X und Y, die das Wort 'Deutschland' im Titel haben, zurück". Das Backend durchsucht anschließend alle vorhandenen Daten nach dem gegebenen Muster, stellt die gefundenen Daten zusammen und fügt ggf. weitere Informationen wie Bilder-URLs etc. hinzu.

4

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

1.2.2 Anforderungen an XML

Das gelieferte XML muss zunächst im Frontend geparst und "manuell" ausgelesen werden. Dieser Prozess ist fehleranfällig, wenn sich beispielsweise etwas am XML ändert oder unvorhergesehene Tags dazukommen. Daher sind folgende Anforderungen an das XML nötig, um eine möglichst performante Seite zu gewährleisten: • Im XML sind nur die Daten vorhanden, die das Frontend benötigt und am Ende auch angezeigt werden. • Der Aufbau der XML ist klar definiert. Sprich, welche Tags wo vorkommen, wofür diese verwendet werden und was sie aussagen. • Kleine XML-Dateien sind besser als sehr große. Gleichzeitig gilt aber auch: Je weniger Requests das Frontend an das Backend stellen muss, desto besser.

1.2.3 Bildausgabe

Damit das Frontend die im Design vorgesehenen Bilder anzeigen kann, müssen diese vom Backend übergeben werden. Um eine gute Performance und Ladezeit der Website zu gewährleisten, müssen die Bilder in verschiedenen Auflösungen bzw. Größen vorliegen. Diese entsprechen der Darstellung der jeweiligen Responsive-Stufen. Es sind drei Responsive-Stufen vorgesehen (Smartphone, Tablet, Desktop). Zusätzlich kann für die vergrößerte Darstellung der Bilder eine hohe Auflösung (über alle Viewports einheitlich) bereitgestellt werden,

Folgende Informationen benötigt das Frontend von der API, um Bilder darzustellen: • URLs (Für alle Versionen des Bildes) • Größen (Die Pixelbreite der Bilder für alle Versionen) • Bildbeschreibung • Copyright-Hinweis • Alt-Text (Beschreibung, was auf dem Bild zu sehen ist, für BITV/SEO)

1.2.4 Beispiel-Rückgabe des Backends

{ "images": [ { "url": "https://example.com/images/image1_200.jpg", "width": 200 }, { "url": "https://example.com/images/image1_400.jpg", "width": 400 }, { "url": "https://example.com/images/image1_600.jpg", "width": 600 } ], "image_alt": "Hier Text", "image_desc": "Hier Text", "image_copyright": "Bundesarchiv 2022", }

1.2.5 Anforderungen an die Bilder

• Müssen im richtigen Format vorliegen, so wie das Design die Bilder vorsieht (z.B. 16x9)

5

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

• Müssen in den verschiedenen Responsive-Größen vorliegen (z.B. 112x200px, 225x400px etc.) • Müssen fürs Web optimiert sein (JPG-Format, komprimierte und kleine Dateigröße) • Alternativtext muss vorhanden sein

Die Auflistung der Formate und Größen je Komponente sind den Layouts und dem Feinkonzept zu entnehmen. Die technische Umsetzung zum Vorhalten der Bilder sowie die redaktionelle Pflege der Bilder und Bildinformationen obliegt dem Bundesarchiv.

1.3 Weitere Anforderungen für verschiedene

Leistungsbestandteile

1.3.1 Anforderungen an die Suche

Die Seite der Such-Funktion besteht aus der Komponente der Suche-Seite, in dieser werden die Unterkomponenten zu einem Gesamtbild zusammengefügt. Als Unterkomponenten sind die Suche-Header-Komponente, die Listen-Komponente und die Such-Listen-Item-Komponente definiert.

Die Suche-Header-Komponente stellt das Eingabefeld für den Suchbegriff sowie die Filterfunktionen für Kategorie und Zeitraum bereit. So lange der Benutzer keine Suchanfrage ausgelöst hat, wird auf der Seite ein statischer Hinweistext zur Nutzung der Suchfunktion ausgegeben.

Sobald der Benutzer eine Suchanfrage auslöst, werden die Parameter des Suchbegriffs sowie die Werte der ausgewählten Filter als Request Parameter der URL angehängt und mittels des von Angular definierten Navigator Service an den Resolver weitergeleitet.

Dieser Resolver nimmt diese Parameter entgegen und löst einen Request mit den vom Benutzer ausgewählten Werten an die API weiter. Sobald die API ein Resultat im JSON Format zurückgibt, werden diese Daten von der Suche-Seite-Komponente entgegengenommen und auf die entsprechende Komponenten-Logik abgebildet, so dass die Daten dargestellt werden können.

1.3.2 Pflege Statischer Labels

Die statischen Texte für Labels, Copyrights etc. die vom Bundesarchiv übermittelt wurden, sind eng mit dem Code verbunden. Das heißt diese Texte stehen im direkten HTML oder sind in den Komponenten angegeben. Änderungen dieser Texte muss ein Entwickler händisch erledigen. Konkret muss gesucht, angepasst, das Projekt erneut durchgebaut und anschließend bereitgestellt werden. Eine „schnelle“ redaktionelle Anpassung über die API ist in diesem Fall nicht gegeben.

6

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

2 Frontend-Konzept

2.1 Einleitung

Frontend-Konzept für die Website der Kabinettsprotokolle des Bundesarchivs. Die Datenstruktur basiert auf Angular.

2.2 Nutzerführung

Die Nutzerführung ist anhand der abgebildeten visuellen Darstellung der Seitenstruktur zu erkennen die den Fokus auf die technische Hierarchie der einzelnen Seiten legt. Ziel der Hauptseiten sind die jeweils dazugehörigen Protokolle. Über die Protokolle (wie auch über den Header) gelangt man zu den Geschäftsordnungen.

7

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

Hauptseiten

8

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

Statische Unterseiten im Header und Footer *Siehe genaue Auflistung in 4.1 Seiten-URL

9

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

2.3 Technology Stack

2.3.1 Build-Prozess

Am Ende des Entwicklungsprozesses werden als Resultat statische Dateien ausgeliefert (siehe Basistechnologie). Die Arbeit erfolgt jedoch nicht direkt in diesen Dateien, sondern in sogenannten Source-Dateien. Der Build-Prozess transpiliert/kompiliert die Source-Dateien, bindet dabei eventuell benötigte Frameworks, Polyfills etc. ein und kann die Dateien nachfolgend in minimierter Form bereitstellen. Der Einsatz eines Build-Prozesses erleichtert die Arbeit beispielsweise in der Vermeidung von Code-Duplikaten sowie durch das automatische Durchlaufen von Maßnahmen zur Qualitätssicherung.

Für das Erzeugen der einzelnen, für die Auslieferung bestimmten Dateien werden darüber hinaus weitere, spezifische Node-Pakete über NPM (https://www.npmjs.com/) bezogen.

Der Build-Prozess gliedert sich im Wesentlichen in vier Teile: • Erzeugen der verschiedenen HTML-Seiten bzw. deren Markup aus Content- JSONs und Templates (siehe 3.5.4 Komponentensystem und Templating ) • Erzeugen der einzelnen JavaScript-Komponenten aus Typescript-Dateien (siehe 3.5.4 Komponentensystem und Templating“ ) • Erzeugen der CSS-Dateien aus ihren SCSS-Gegenstücken (siehe Designumsetzung) • Optimierung von statischen Dateien wie Bildern etc.

2.3.2 Basistechnologie

Die ausgelieferten Seiten basieren auf den folgenden Web-Standards: • HTML 5 - Strukturierung der Webseiten-Inhalte in semantischer Form (https://www.w3.org/TR/html5/) • CSS - Darstellung der Inhalte gemäß dem vorgesehenen Design (https://www.w3.org/Style/CSS/) • JavaScript - Dynamische Funktionen, die zur Laufzeit im Browser des Webseitenbesuchers ausgeführt werden

XX gewährleistet eine Auslieferung von validem HTML5 nach den Standards des W3C (https://validator.w3.org/).

Aufgrund von Unterschieden in der Unterstützung von CSS-Features innerhalb der verschiedenen Browser und Abnahmegeräte kann die Auslieferung von validem CSS nicht immer vollständig gewährleistet werden. Im Hinblick z.B. auf die Barrierefreiheit ist dies aber auch nicht relevant. Die optische Darstellung des Layouts bleibt hiervon ebenfalls unberührt.

2.3.3 Versionierung

Die Arbeiten am Projekt werden in einem Git-Repository versioniert und als ZIP-Datei zur Verfügung gestellt. Es handelt sich hierbei ausschließlich um den Sourcecode (siehe Bundesarchiv-Angular-Projekt.zip unter 1.1 Anlagen).

Dabei verwendet XX die Möglichkeiten des Branchings von Git intensiv. Alle in sich abgeschlossenen Features erfolgen auf einem separaten Branch und werden erst in den Hauptbranch überführt, wenn sie abgeschlossen und geprüft wurden. So wird ein sauberer Stand auf dem Hauptbranch gewährleistet.

2.3.4 Qualitätssicherung

XX ergreift verschiedene Maßnahmen zur Qualitätssicherung und Vermeidung von Fehlern. Diese beinhalten in der Frontend-Umsetzung im Speziellen:

10

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

• Automatisches Linting des HTMLs integriert in den Build-Prozess. • Prüfung der Variablen-Typen gemäß Definition im Typescript, integriert in den Build- Prozess. Bei Fehlern wird der Build-Prozess abgebrochen. • Automatische Erweiterung des CSS-Codes durch Hinzufügen von gegebenenfalls notwendigen Vendor-Prefixes für ältere Browser zum Erreichen größtmöglicher Kompatibilität (durch Autoprefixer, basierend auf PostCSS, https://autoprefixer.github.io/). • Die ausgelieferten Musterseiten werden einem Performance-Test mit Lighthouse (in aktuellen Chrome-Versionen in deren DevTools integriert) unterzogen. • Code-Review durch andere projektbeteiligte Entwickler • Erstellung und Ausführung von Testplänen mittels TestFLO.

2.3.5 Innerhalb des ausgelieferten Codes verwendete Frameworks

und Libraries

Neben den Tools, die im Workflow selbst genutzt werden, wird das externe Framework Angular in Version 13.3 eingesetzt.

Bei Bedarf können zudem weitere Frameworks eingebunden werden. Eine stets aktuelle Liste ist in der Datei package.json hinterlegt. Alle Abhängigkeiten sind dort aufgeführt (siehe 1.1 Anlage, Bundesarchiv-Angular-Projekt.zip)

2.3.6 XML Parser

Der XML Parser ist eine JavaScript-Klasse, welche XML-Code entgegennimmt und diesen in für den Browser lesbares HTML umwandelt, sodass alle im XML vorhandenen Kodierungen und Funktionalitäten (wie beispielsweise Kommentare) ausgegeben werden können.

Der Code des Parsers ist im Projekt unter dem Pfad zu finden. \src\app\features\text Verwendet werden kann der Parser über die Angular Component . Diese erhält als comp-text Property das XML und rendert dann das entsprechende HTML. Intern nutzt die Component den XMLParser.ts. Dieser iteriert rekursiv über alle XML Nodes. Pro Node wird anhand des Namens der Node eine passende Factory aufgerufen, welche alle Informationen der Node erhält (z.B. ). Die Factory entscheidet dann anhand des Kontextes, ggf. CellElementParser vorhandenen Attributen etc., welches HTML Element erstellt werden soll und konfiguriert dieses mit benötigten CSS Klassen oder weiteren Attributen.

2.4 Abnahmesysteme

Folgende Systeme wurden bei der Entwicklung berücksichtigt und werden entsprechend unterstützt:

11

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

2.5 Designumsetzung

2.5.1 Responsive-Design

Die Umsetzung des Frontends erfolgt auf Basis des Responsive-Design-Konzeptes. Dies bedeutet, dass für alle Geräte-Klassen dieselbe Seite ausgeliefert wird.

Gerätespezifische CSS-Regeln sorgen danach für die optimale Darstellung auf dem entsprechenden Zielgerät.

2.5.1.1 Mobile First Bei der Umsetzung des Designs wird der "Mobile First"-Ansatz angewendet. Dies bedeutet, dass alle CSS-Regeln vom kleinsten Viewport ausgehend auf größere Viewports weitervererbt und gegebenenfalls angepasst werden.

2.5.1.2 Breakpoints Es sind bestimmte Viewport-Breiten vorgesehen, an denen sich das Design der Seite verändert. Innerhalb dieser Bereiche verhält sich die Seite (mit Ausnahme ab dem höchsten Breakpoint) fluide, d.h. der Content breitet sich auf die gesamte zur Verfügung stehende Viewport-Breite aus.

Nicht jede Komponente wird individuell für alle Breakpoints optimiert. Die Elemente innerhalb von Komponenten richten sich am Gestaltungsraster aus. Ziel ist eine harmonische Darstellung aller Seiteninhalte.

12

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

2.5.2 Atomic Design

XX verwendet in der Frontend-Entwicklung einen Ansatz, der die Struktur von den kleinsten (Atome) bis zu den größten Bestandteilen (Module) der Seite definiert. Jeder dieser Bestandteile wird innerhalb der Entwicklungsumgebung separat entwickelt und gepflegt. Dies erhöht die Möglichkeiten der Wiederverwendung sowie Anpassung erheblich.

Für jeden Bestandteil wird mindestens ein HTML-Template erstellt. Wird Styling benötigt, so kommen eine oder mehrere SCSS-Dateien, für JavaScript-Logik eine oder mehrere TypeScript- Dateien hinzu.

Die Aufteilung der Bestandteile stellt sich wie folgt dar: • Atome

bezeichnen oft benutzte HTML-Elemente wie Buttons, Form-Elemente etc. o meist handelt sich um native HTML-Elemente, die über Klassen zusätzlich dem o Layout entsprechend gestylt werden • Elemente

entsprechen wiederverwendbaren HTML-Teilen innerhalb von Seiten, Modulen o oder anderen Elementen

sollen an beliebigen Stellen einsetzbar sein, solange es der Kontext des o Layouts zulässt • Module

sind wiederverwendbare HTML-Teile innerhalb von Seiten o können Elemente und Atome enthalten, aber keine anderen Module o

2.5.3 Theming

Farben, Schriftgrößen und Ähnliches werden im CSS als Variablen angelegt. Dadurch ist eine einfache Bereitstellung von separaten Theme-Dateien möglich.

Pro generierter CSS-Datei können verschiedene CSS-Variablen genutzt werden, sodass pro Seite mit Theming jeweils komplett eigene CSS-Dateien ausgeliefert werden.

2.5.4 Komponentensystem und Templating

Es werden das Komponentensystem und Templating von Angular verwendet. • Komponentensystem: https://angular.io/guide/component-overview • Templating: https://angular.io/guide/template-overview

2.6 Gestaltungskonzept

2.6.1 Standardschriften

XX nutzt Schriften in den Dateiformaten .woff und .woff2. Diese decken alle für die Umsetzung relevanten Browser- und OS-Versionen ab.

13

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

2.6.2 Farben

Alle im Layout festgelegten Farbcodes werden, wie in vorigen Punkten bereits kurz erwähnt, in eine entsprechende SCSS-Datei überführt und können so bei Bedarf seitenweit angepasst werden.

2.6.3 SVG-Icons

Im Projekt werden SVG-Icons eingesetzt.

2.7 Patternlibrary

Eine Patternlibrary ist eine statische Sammlung einzelner Bestandteile des Projektes. Sie dient gleichermaßen zur Übersicht für weitere Entwicklungen als auch zur Dokumentation der bisherigen Entwicklung. Sie ist im gleichen Rahmen wie die eigentlichen, statischen Exporte abrufbar. XX wird eine solche Patternlibrary (siehe 1.1 Anlagen) zur Verfügung stellen. Dabei werden auch die jeweils verfügbaren Varianten eines "Patterns" abgebildet.

2.8 Performance

Um eine performante Auslieferung der Seite zu gewährleisten, nimmt XX bereits während der Entwicklung folgende Maßnahmen vor: • Reduzierung der verwendeten Dateien aus Frameworks und Libraries (vor allem JavaScript und CSS) auf das notwendige Minimum. • Optimierung von Bildmaterial, dass im Rahmenlayout bzw. den Musterseiten Verwendung findet • Unnötige Anfragen an die API wurden bei der Entwicklung vermieden. Sprich die kleinste Menge an Datenpaketen wird angefragt.

14

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

3 Barrierefreiheit

Die Umsetzung erfolgt gemäß der Verordnung BITV 2.0. In diesem Rahmen legt XX bei der Entwicklung besonderes Augenmerk auf die folgenden Punkte: • Sinnvolle Ausgabe der Seite mit einem Screenreader, z.B JAWS • Bedienbarkeit der Webseite über die Tastatur • Semantisch korrekte Strukturierung der Webseite • Auslieferung von validem HTML • Konsequente Nutzung von alt-Attributen • Nutzung von ARIA-Attributen, wenn sonstige Auszeichnungen die Semantik nicht klar widerspiegeln

3.1 Sonstige Optimierungen

3.1.1 Favicon

XX bindest ein Favicon ein, das auf allen gängigen Geräten angezeigt wird und auch beim Hinzufügen zum Startscreen/Desktop optimal dargestellt wird.

3.1.2 SEO

XX nimmt eine On-Page Optimierung gemäß folgender Grundsätze vor: • semantisch korrekte Nutzung von HTML-(5)-Tags • sinnvolle Überschriftenhierachie • Optimierung der Performance gemäß Kapitel Performance • Entwicklung einer optimierten Mobilversion im Rahmen des Responsive Design

3.1.3 Druckversion

Es wird eine druckbare Version der Seiten gewährleistet. • Die Druckfunktion wird über die native Browserfunktion ausgelöst. • Rahmenlayout

Das Logo der Kabinettsprotokolle wird angezeigt. o Alle anderen Bestandteile des Rahmenlayouts (Header/Footer) werden nicht o angezeigt. • Die Seiten sind zum Ausdruck auf A4-Hochformat aufbereitet (für die entsprechenden Abnahmesysteme) • Die Darstellung von Modulen ist an das Druckformat und die technischen Möglichkeiten der Druckausgabe (des jeweiligen Browsers) angepasst.

Es ist auch möglich, dass Elemente aufgespalten oder umsortiert werden. o Eine sinngemäße und zweckmäßige, lesbare Darstellung wird angestrebt. o Gewisse Elemente, die in der Druckansicht keine Funktion haben (z.B. Icons, o Slider-Pfeile etc.), sind ausgeblendet. • Die Druckausgabe beinhaltet keine Bilder.

Die Bildteile der Bände sind davon ausgenommen. o

15

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

• Hintergrundfarben/-grafiken sind grundsätzlich deaktiviert. • Die Schriftfarbe ist immer schwarz. • Link-Ziele werden nicht ausgeschrieben. • Listen

Es wird das in der Druckansicht dargestellt, was zum jeweiligen Zeitpunkt auf o der Webseite sichtbar ist. • Spezifische Ausprägungen oder Ausnahmen wurden innerhalb der Story-Tickets der einzelnen Seiten/Module definiert.

Das HTML der Druckversion unterscheidet sich lediglich darin, dass eine Print-Theming-CSS- Datei eingebunden wird, die bestimmte Elemente überschreibt/ausblendet.

16

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

4 Git-Workflow

Der Git-Workflow des Frontend-Repo's soll auf den Ticket-Workflow hin optimiert werden.

• Wenn ein Elternticket in Arbeit genommen wird, wird ein Feature-Branch für ein Elternticket vom Master-Branch abgezweigt

auf diesem Branch selber erfolgen keine Commits außer Merge-Commits o gleich zu Beginn wird ein MR erstellt und auf WIP gesetzt o • Wenn ein Unterticket in Arbeit genommen wird, wird ein Feature-Branch für ein Unterticket vom Feature-Branch des Elterntickets abgezweigt auf diesem Branch erfolgt die Arbeit für diesen Teil des Features o es kann beliebig oft in den development-Branch gemerged werden (z.B. um o zwischenzeitlich zu testen)

am Ende der Arbeiten o  wird in den development-Branch gemerged  wird ein MR zurück in den Feature-Branch des Elterntickets erstellt • es erfolgt eine Code-Review durch einen anderen Entwickler; wenn bestanden wird der Branch in den Feature-Branch des Elterntickets gemerged • Es können mehrere Feature-Branches für Elterntickets parallel existieren • Die Arbeit mit den Branches für Untertickets kann sowohl linear erfolgen, wenn die Teil- Features aufeinander aufbauen, jedoch auch parallel, wenn sie unabhängig voneinander sind • Am Ende der Arbeiten für ein Elternticket wird der WIP-Status des MR entfernt

der MR kann jetzt vom Tester angenommen werden, sobald die abschließende o QS des Features auf DEV erfolgreich war • Auf dem Master können beliebig Tags erstellt werden • Auf dem development-Branch erfolgen keine Commits außer Merge-Commits

17

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

4.1 Seiten-URLs

Die folgende Übersicht beschreibt die Seiten, welche statisch (z.B. Startseite) oder dynamisch (z.B. Registereinträge) angelegt werden.

4.1.1 Hauptseiten

18

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

4.1.2 Statische / Unterseiten

19

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

4.2 Installationsanleitung inkl. Abhängigkeiten

ist, führen Sie ‚npm -v‘ in der Konsole aus.

Installationsanleitung Führen Sie, innerhalb des Root-Verzeichnisses dieses Projekts, ‚npm install‘ aus, um alle Abhängigkeiten herunterzuladen und zu installieren.

Ebenfalls sollten Sie ‚npm install -g @angular/cli‘ ausführen, um den Angular CLI zu installieren. Mit diesem lassen sich neue Angular Projekte / Applikationen erstellen oder Entwicklungsarbeiten an bestehenden Projekten angenehmer durchführen.

Sobald die Installation abgeschlossen ist, können Sie den Befehl ‚ng serve‘ im Root-Verzeichnis ausführen. Dies baut das Projekt einmal für die Entwicklungsumgebung durch und stellt es lokal unter der Adresse ‚localhost:4200‘ bereit.

Grundlegende Bereitstellung auf einem Remote-Server

Für die einfachste Bereitstellung erstellen Sie einen Produktions-Build und kopieren das Ausgabeverzeichnis auf einen Webserver. Siehe hierzu den Angular-Build-Prozess: https://angular.io/guide/build

Beginnen Sie mit dem Produktionsaufbau mittels Ausführung von ‚ng build‘ im Root-Verzeichnis des Projekts.

Anschließend kopieren Sie alles im Ausgabeordner (standardmäßig dist//) in einen Ordner auf dem Server.

Konfigurieren Sie den Server so, dass Anfragen nach fehlenden Dateien an index.html umgeleitet werden. Dies ist die einfachste produktionsbereite Bereitstellung Ihrer Anwendung.

Um verschiedene Umgebungen definieren zu können, wird das Standardverfahren von Angular genutzt. Dies ist unter dem Link der Angular Doku näher erläutert: https://angular.io/guide/build#configuring-application-environments

4.3 Betriebskonzept

4.3.1 Einleitung

Für die Entwicklung bzw. die Live-Seite werden folgende Systeme und Konfigurationen benötigt:

4.3.2 Development

Das Entwicklungssystem steht für die regelmäßige Ausrollung neuer (auch unfertiger) Funktionen bereit. Der Testprozess wird im Entwicklungssystem gestartet und Abweichungen von den Anforderungen direkt durch die Entwickler auf dem Entwicklungssystem behoben. Nach erfolgreicher Qualitätssicherung auf dem Entwicklungssystem durch XX können Neuerungen auf das Staging-System übertragen werden.

20

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

Es wird ein Web-Server benötigt, auf dem die eigentliche Website der Kabinettsprotokolle mit Seiten und echten Daten dargestellt wird. Die separate Pattern Library soll als Sammlung einzelner Module und möglicher Ausprägungsvarianten dienen.

4.3.2.1 Website • Static File Server • FTP-/SSH-Zugang, um Daten hochzuladen • Entsprechend konfiguriert, sodass bei allen Requests entweder die angefragte Datei oder, falls nicht vorhanden, die index.html zurückgegeben wird.

Weitere Infos zur Server-Konfiguration für o Angular: https://angular.io/guide/deployment#server-configuration • Erreichbar über eine Dev-(Sub)Domain • Nicht öffentlich aufrufbar, nur von Stakeholdern (z.B. über IP-Whitelist)

4.3.2.2 Pattern Library (Storybook) • Static File Server • FTP-/SSH-Zugang, um Daten hochzuladen • Entsprechend konfiguriert sodass bei allen Requests entweder die angefragte Datei oder, falls nicht vorhanden, die index.html zurückgegeben wird. • Erreichbar über eine entsprechende Dev-Patternlab-(Sub)Domain • Nicht öffentlich aufrufbar, nur von Stakeholdern (z.B. über IP-Whitelist)

4.3.3 Staging

Zur Anpassung der Api-URL und der Ressourcen-URL für andere Systeme können Meta-Tags in die index.html des durchgebauten Projektes eingefügt werden.

<meta name=”resourceURL” content=”YOUR RESOURCE URL”/>

Sollten diese Meta-Tags nicht angegeben werden, werden die URLs der Dev-Umgebung verwendet.

Jedoch möchten wir darauf hinweisen, dass dies eventuelle ungeahnte Sicherheitslücken öffnen könnte sowie vom normalen Workflow mit Angular und dem Build-Prozess von mehreren Entwicklungsumgebungen stark abweicht.

Für die Produktions-Umgebung legen wir den Angular Build-Prozess für mehrere Umgebungen nahe: https://angular.io/guide/build

4.3.4 Production

Das Produktivsystem stellt die Ausgabe für die Endnutzer dar. Auf diesem System werden nach Übertragung der Neuerungen auf das System keine Anpassungen mehr vorgenommen. Vor Übernahme der Funktionen auf das Produktivsystem ist der entsprechende Testprozess abzuschließen. Die Pattern Library wird hier nicht benötigt.

4.3.4.1 Website • Identisch zum Dev-System • Öffentlich aufrufbar über die Live-Domain

21

Online-Präsentation der Edition “Die Kabinettsprotokolle der Bundesregierung” – Technische Dokumentation

4.4 Abnahmeplan

Die Abnahme wird wie im Vertrag unter § 7 beschrieben durchgeführt.

Die Qualitätssicherung der Entwicklung als Voraussetzung für die Abnahme wird gemäß des BARCHIV-Testkonzepts vorgenommen (siehe Leistungsbeschreibung 4.6.7).

Die Finalisierung der einzelnen Bestandteile bis zur Abnahme erfolgt in regelmäßigen Feedbackschleifen via Emailkorrespondenz. Hierbei wird frühestmöglich Feedback eingebunden, um möglichst genau auf die Anforderungen einzugehen.

22