RC3 Hub/Gateway (und Plain UI Frontend)

Datenmodell

als PDF: Grobes Datenmodell und automatisch exportiertes ER-Diagramm (kann Spuren von Unübersichtlichkeit enthalten)

REST API

Am Beispiel der Konferenz-Slug "rc3", grundsätzlich sind alle hier aufgeführten Endpoints per GET abrufbar (Restriktionen bei nicht-öffentlichen Events, etc. sind möglich). Manche Endpunkte sind zusätzlich "schreibbar" und können zur Anlage bzw. Bearbeitung der jeweiligen Daten genutzt werden.

Testinstanz: https://api-test.rc3.cccv.de/

Per POST werden neue Einträge angelegt, per PUT bestehende verändert. Details zu den einzelnen Endpunkten folgen in Kürze™.

Plain UI

Es handelt sich um eine Darstellung der Konferenz-Inhalte als simples Frontend ohne viel Schnick-Schnack.

Testinstanz: https://app-test.rc3.cccv.de/

Navbar

Bietet eine von allen Seiten gemeinsam einbindbare Navigationsleiste im jeweiligen Congress-Design. (not implemented yet)

Lokale Entwicklung

Dieses Projekt basiert auf Python 3.8+ und Django 3.1+.

Initiale Einrichtung

1. Installiere, falls noch nicht geschehen, Python in Version 3.8 (oder höher) und habe eine PostgreSQL-Datenbank zur Hand (geht potenziell auch mit sqlite aber das ist nicht getestet). Außerdem wird unter Umständen GNU gettext benötigt, wenn man Übersetzungen kompilieren will.
   • Linux: Pakete python3, postgresql und gettext
   • Mac: brew install python3 postgresql gettext bzw. https://postgresapp.com/
   • Windows: latest stable Python 3 release und PostgreSQL Installer und gettext binaries
2. Klone dieses Repository an beliebigen Ort.
3. Gehe via Terminal/Konsole in das Unterverzeichnis src.
4. Falls du kein direnv benutzt:
   1. Richte ein venv ein: python3 -m venv .venv
   2. Aktiviere das venv: . .venv/bin/activate
5. Installiere die benötigten Pakete: python3 -m pip install -r requirements.txt psycopg2-binary
6. (falls nicht bereits vorhanden) lege einen PostgreSQL-User an (createuser -P rc3app) sowie eine Datenbank (createdb -O rc3app rc3db) - unter Linux ggf. via sudo -u postgres
7. Lege eine Datei local_settings.py in src/rc3platform/ an (Dokumentation zur Datenbankkonfiguration in der Django-Dokumentation):

DEBUG = True
ALLOWED_HOSTS = ['127.0.0.1', 'localhost']
SESSION_COOKIE_SECURE = False
SESSION_COOKIE_DOMAIN = None
IS_API = True
IS_FRONTEND = True
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'  # "send" emails as console output

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'rc3db',
        'USER': 'rc3app',
        'PASSWORD': '<kennwort-aus-dem-createuser-aufruf>',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

8. Lege die Datenbanktabellen an: ./manage.py migrate
9. Richte einen Admin-Nutzer (für die Anwendung) ein: ./manage.py createsuperuser
10. optional: Import von Demo-Daten: ./manage.py loaddata ./fixtures/36c3-and-dummy-rc3.json

Nutzung

1. Gehe in das src Verzeichnis, nicht-direnv-Nutzer müssen das venv manuell aktivieren (siehe oben)
2. Wende ggf. vorhandene DB-Migrations an (wenn du gerade aus dem Git geupdatet hast): ./manage.py migrate
3. Stelle sicher dass alle Translations aktuell sind: ./manage.py compilemessages
4. Starte den Dev-Server: ./manage.py runserver
5. Besuche die lokale Instanz: Admin-Seite, API und plainui-Frontend

PlainUi Structure

• jinja2/plainui
  • components
  • tbd.
• styles
  • components: components styles, die in rc3.scss eingebunden werden
  • utils: settings, die selbst keinen output generieren (z.B. Variablen, Mixins), damit sie in unterschiedlichen files verwendet werden können
  • rc3.scss: Hauptdatei, welche anschließend in CSS konvertiert wird.
  • alle Files, die auf der gleichen Ebene wie rc3.scss liegen, werden einmalig in das rc3.scss eingebunden.
• static/plainui
  • img: statische Bilder
  • fonts: importierte Schriften
  • das generierte css - rc3.css

CSS Kompilieren (PlainUi)

1. Gehe in das Verzeichnis src/plainui/
2. Führe yarn aus, um die node_modules zu generieren
3. Führe yarn build aus um das CSS zu kompilieren
4. Um das CSS beim Entwickeln automatisch neu zu kompilieren gibt es yarn watch

Components

Wiederverwendbare Elemente können als Komponenten integriert werden. Dafür gibt es jeweils 2 "components"-Ordner. Die HTML-Komponenten befinden sich in plainui/jinja2/plainui/components. Sollten zusätzliche Styles benötigt werden, können diese in plainui/styles/components hinzugefügt werden, welche anschließend in rc3.scss integriert werden. Wichtig ist, ein eigenes File pro Komponente anzulegen. Für Jinja eignen sich dazu Macros oder Includes. Zusätzlich ist die Komponente in der Übersicht hinzuzufügen - lokal erreichbar unter http://localhost:8000/component_gallery.

Debugging DJANGO

Context im HTML-File ausgeben:

    <pre>{% debug %}</pre>

oder:

    <pre>
        {{ show_vars(myContextElement) }}
    </pre>

Übersetzungen extrahieren & compilieren

• ./manage.py makemessages
• Die Übersetzungsdateien in <app>/locale/<sprache>/LC_MESSAGES/django.po wurden um alle neuen Übersetzungsstrings erweitert. Bearbeiten und jeweils bei msgstr die Übersetzungen einfügen!
• ./manage.py compilemessages
• Zum Ausprobieren müsst ihr django neu starten um die neuen Übersetzungsdateien zu laden

Übersetzungen definineren

• in Python: gettext wie üblich in Django, siehe Doku
• in jinja2-Templates via _, bspw. {{ _("Settings") }} oder mit Platzhalter {{ _("Hello, %(username)s", username=user.display_name) }}

Tests

Es gibt Django (Unit-)Tests für die einzelnen Apps. Diese finden sich jeweils im tests Ordner der App. Außerdem gibt es im repository root unter tests auch noch einfache Integrationstests.

Django Tests ausführen

Um die Tests ausführen zu können muss der Datenbanknutzer das Recht haben neue Datenbaken anzulegen. Dafür mit psql postgres die Datenbankkonsole starten. Dort ALTER USER rc3app CREATEDB; ausführen (ggf. rc3app durch den gewählten Nutzernamen ersetzen). Am Ende mit Strg-D Konsole wieder schließen.

Manche Tests benötigen, die kompilierten Übersetzungen. Deshalb ist es sinvoll vor der Testausführung ./manage.py compilemessages auszuführen.

Um alle Tests auszuführen in das src Verzeichnis wechseln und ./manage.py test ausführen.
Um nur die Tests einer App auszführen stattdessen ./manage.py test <app>.tests ausführen.
Hilfreiche Argumente sind -v 2 um die ausgeführten Tests anzuzeigen und --failfast um nach dem ersten Fehler abzubrechen.
Für weitere Infos zu dem Befehl ist https://docs.djangoproject.com/en/3.1/ref/django-admin/#django-admin-test hilfreich.

Um eine Ausführungsgebung zu verwenden die ähnlicher zu der der CI ist, kann DJANGO_SETTINGS_MODULE=rc3platform.settings.ci ./manage.py test verwendet werden.