Regatta Results – WordPress-Plugin

Empfängt die Live-Daten, die die Zeitnahme-Software Aquarius per HTTP an einen Ergebnis-Server schickt, speichert sie in eigenen Datenbanktabellen und zeigt Zeitplan, Startlisten und Ergebnisse auf der Website an.

Entwickelt für regatta-celle.de, aber bewusst so gebaut, dass andere Veranstalter es ebenfalls einsetzen können.

Sprache: Die Quelltexte sind englisch, die deutsche Übersetzung liegt fertig kompiliert bei (languages/regatta-results-de_DE.mo). Auf einer deutschen WordPress-Installation ist die Oberfläche also deutsch – so, wie es wordpress.org erwartet, wo Übersetzungen über translate.wordpress.org laufen.

Installation (Testinstanz)

1. Den Ordner regatta-results nach wp-content/plugins/ kopieren.
2. Im Backend unter Plugins aktivieren. Dabei werden die Tabellen angelegt und ein erster API-Zugang aquarius mit generiertem Passwort erzeugt.
3. Regatta → Benutzer öffnen. Das generierte Passwort wird dort genau einmal angezeigt – notieren.
4. Regatta → Werkzeuge → Selbsttest ausführen. Der Test prüft, ob der Webserver den Authorization-Header an PHP durchreicht. Schlägt er fehl, steht auf derselben Seite der passende .htaccess-Schnipsel.
5. Regatta → Werkzeuge → Demodaten anlegen und den angezeigten Shortcode auf eine Seite setzen – damit lässt sich die Darstellung ohne Zeitnahme testen.

Darstellung

Die Ausgabe orientiert sich an regattaergebnis.info:

• Zeitplan – nach Wettkampftagen gruppiert, Spalten R-Nr., Lauf, Rennen, Zeit, Status und ein Link. Vor dem Start führt der auf die Startliste, ab dem Start auf das Ergebnis. Pausen erscheinen als eigene Zeile.
• Startliste – Bahn, StNr, Boot / Mannschaft mit Ruderern samt Jahrgang. Der Verein steht hinter den Namen nur bei einer Renngemeinschaft; sitzt die Mannschaft in einem Verein, steht der schon im Bootsnamen.
• Ergebnis – zusätzlich Rang und je eine Spalte pro Zwischenzeit. Überschrift ist die Distanz (z. B. „500 m"), und ohne bekannte Distanz heißt die Zielspalte schlicht Zeit. In der Zelle steht die Zeit, der Rang an dieser Marke in Klammern und darunter der Rückstand in Hundertsteln. Zeiten erscheinen erst, wenn der Lauf beendet ist. DNF/DSQ werden so ausgegeben, wie Aquarius sie liefert.

Ein einziger Shortcode genügt: [regatta_schedule] zeigt den Zeitplan und wechselt über die Links darin in dieselbe Seite mit Startliste bzw. Ergebnis (?rr_comp=…&rr_view=…), von wo ein Rücksprung zum Zeitplan führt.

Stand der Regatta

Über den Tabellen steht eine Statuszeile, die dem Ablauf folgt:

Pausen und abgesagte Läufe zählen dabei nicht mit – ein abgesagter Lauf wird nie beendet und würde „alle durch" für immer verhindern. Solange die Regatta bei Ausschreibung steht, zeigt [regatta_schedule] die Rennliste statt eines Zeitplans, auch wenn die Zeitnahme schon einzelne Läufe geschickt hat. Der Stand lässt sich je Veranstaltung von Hand festnageln.

Mobil: Unter 720 px Breite lösen sich die Tabellen in Karten auf – jede Zeile wird ein Block, die Spaltenüberschrift steht als Label davor, der Rang bildet die Kopfzeile der Karte. Es wird nicht horizontal gescrollt.

Weitere Shortcodes

live="1" lädt den Block per JavaScript im eingestellten Intervall neu (Standard 30 s, Untergrenze 5 s). Serverseitig wird dabei dieselbe Template-Funktion aufgerufen, es gibt also keine doppelte Render-Logik. Eine Zahl größer eins setzt den Takt für genau diese Seite: [regatta_schedule live="5"]. live="0" schaltet die Aktualisierung ab.

Nachgeladen wird nur die Tabelle, die Seite selbst bleibt stehen. Im Hintergrund-Tab pausiert die Abfrage und holt beim Zurückwechseln nach; eine fehlgeschlagene Abfrage lässt den letzten Stand stehen.

Templates lassen sich im Theme überschreiben: regatta-results/schedule.php, comp.php, events.php, sponsor-frame.php.

Benutzerverwaltung

Unter Regatta → Benutzer in zwei Teilen:

1. Zugänge der Zeitnahme – die HTTP-Basic-Konten, mit denen Aquarius sendet. Anlegen, Notiz vergeben, aktivieren/deaktivieren, Passwort neu erzeugen, löschen. Passwörter werden mit wp_hash_password() gespeichert und nur einmal im Klartext angezeigt. Je Zugang werden Anzahl der Requests, Zeitpunkt und IP des letzten Zugriffs geführt; ein Klick auf die Request-Zahl filtert das Protokoll auf diesen Zugang. Optional lässt sich ein WordPress-Konto verknüpfen, um zu dokumentieren, wer den Zugang betreut.
2. Berechtigungen – welche WordPress-Rollen die Regattadaten im Backend verwalten dürfen. Administratoren dürfen immer; weitere Rollen bekommen die Fähigkeit manage_regatta_results.

Wer welche Daten geliefert hat, steht in der Datenbank: events führen api_user_id (Eigentümer), created_by und updated_by, die Tabellen races, comps, entries und results jeweils api_user_id der letzten Schreiboperation. Das Protokoll speichert zusätzlich api_user_id und wp_user_id.

Eine Veranstaltung gehört dem Zugang, der sie angelegt hat – andere Zugänge bekommen 401 und können sie nicht überschreiben.

Sponsoren

Unter Regatta → Sponsoren. Je Sponsor: Name, Logo (Mediathek oder externe Bildadresse), Verlinkung, Platzierung, Reihenfolge, sichtbar ja/nein und optional eine Beschränkung auf eine Veranstaltung.

Platzierungen: oben, unten, links, rechts. Oben und unten sind Banner über die volle Breite, links und rechts sind Seitenflächen, die erst ab 1200 px eingeblendet werden und beim Scrollen stehen bleiben. Zusammen ergeben sie den Rahmen um Zeitplan, Startlisten und Ergebnisse. Links bekommen rel="sponsored nofollow"; ob sie in einem neuen Tab öffnen, ist einstellbar. Der Rahmen lässt sich in den Einstellungen komplett abschalten.

Endpunkte

Aquarius bekommt eine Basis-URL, an die es selbst /event/{uuid} usw. anhängt. Zwei Varianten stehen bereit:

Die Kurz-URL gibt es, weil noch nicht geklärt ist, ob Aquarius einen Pfad in der Server-Adresse akzeptiert oder nur Host + Port. Sie leitet intern auf dieselben REST-Routen um.

Implementierte Routen (gemäß der OpenAPI-Spezifikation von Steffen Christgau):

PUT|DELETE        /event/{uuid}
PUT|DELETE        /event/{uuid}/race/{raceNr}
PUT|DELETE        /event/{uuid}/race/{raceNr}/entries
PUT|PATCH|DELETE  /event/{uuid}/comp/{compNr}
PUT               /event/{uuid}/comp/{compNr}/result
DELETE            /event/{uuid}/schedule
GET               /ping                      (nur für Verbindungstests)

Zusätzlich lesende Endpunkte für das Frontend:

GET /wp-json/regatta-results/v1/public/events
GET /wp-json/regatta-results/v1/public/event/{uuid|slug|id}
GET /wp-json/regatta-results/v1/public/event/{uuid}/schedule?day=&race=
GET /wp-json/regatta-results/v1/public/comp/{id}
GET /wp-json/regatta-results/v1/public/widget/{key}

Sie liefern nur veröffentlichte Veranstaltungen. Neue Veranstaltungen sind standardmäßig nicht öffentlich und müssen im Backend freigeschaltet werden (oder per Einstellung automatisch).

Datenmodell

Ergebnisse werden über comp_id + provider_entry_id + split_number eindeutig gehalten. Kommt eine neue Startliste, bleiben bereits eingegangene Ergebnisse erhalten und werden neu verknüpft – die Reihenfolge von Aquarius' Requests ist damit egal.

Offene Punkte gegenüber der Zeitnahme

1. Basis-URL: Akzeptiert Aquarius eine Server-Adresse mit Pfad (https://host/wp-json/regatta-results/v1)? Falls nein, muss die Kurz-URL genutzt werden – oder wir brauchen einen noch kürzeren Prefix.
2. Auth bei DELETE: In der OpenAPI-Spec fehlt bei einigen DELETE-Operationen der security-Block. Schickt Aquarius den Authorization-Header trotzdem immer mit? Aktuell verlangt das Plugin ihn bei allen schreibenden Zugriffen; fehlende Credentials landen sichtbar im Protokoll.
3. state-Werte: Welche Zahl bedeutet was? Die Zuordnung ist geraten und in den Einstellungen frei editierbar. Aus dem Betrieb ist bekannt, dass Aquarius für „beendet" eine Zahl oberhalb von 4 schickt – welche genau, ist offen. Unbekannte Zahlen fallen auf die nächstniedrigere bekannte Stufe zurück, die oberste ausgenommen: „offiziell" wird nicht geraten. An denselben Schwellen hängen „Startliste ausblenden ab Start" und „Zeiten erst ab beendet", die deshalb noch auf einer Annahme stehen.
4. irm-Codes: Welche Zahl steht für DNS/DNF/DSQ/EXC? Angezeigt wird momentan der mitgelieferte display-Text, das reicht fürs Erste.
5. split_number: In den Fixtures taucht neben 1–3 auch 64 auf (mit irm), im Betrieb zusätzlich 0. Ist 64 ein Marker für „Endergebnis" und 0 der Start? Aktuell gilt der höchste gelieferte Split als Zielzeit, und Split 0 bekommt keine eigene Spalte – er stünde bei jedem Boot auf derselben Zeit.
6. affectedSplits: Sollen Ergebnisse zu diesen Splits, die nicht in updates stehen, gelöscht werden? Das Plugin schreibt derzeit nur die gelieferten Zeilen und löscht nichts.
7. cancel_state: In den Fixtures kommen 0 und 1 vor. Ab welchem Wert gilt ein Boot als abgemeldet? Aktuell blendet das Plugin Boote mit Wert > 1 aus (abschaltbar in den Einstellungen).
8. starlist vs. startlist: Die Fixtures nutzen starlist (ein „l"), die OpenAPI-Spec startlist. Welche Schreibweise sendet Aquarius wirklich? Das Plugin akzeptiert beide – aufgefallen ist es erst durch den Fixture-Test.
9. Reihenfolge/Vollständigkeit: Sendet Aquarius nach „Erstellen" garantiert erst das Event, dann Races, dann Entries/Comps? Das Plugin verlangt das Event vorab (404 sonst), verkraftet aber Comps vor Races.

Veröffentlichung auf wordpress.org

Vorbereitet ist:

• readme.txt im Verzeichnisformat (Kurzbeschreibung, FAQ, Screenshot-Beschriftungen, Changelog, Datenschutzabsatz)
• englische Quelltexte, languages/regatta-results.pot und eine fertige deutsche Übersetzung (.po + .mo)
• .distignore, damit docs/, tests/, tools/ und README.md nicht im Paket landen
• .wordpress-org/icon.svg samt Anleitung, was für das Verzeichnis noch an Bildern fehlt (Banner und Screenshots lassen sich nur als Rasterbilder anlegen)

Vor dem Einreichen noch selbst erledigen:

1. Contributors: in der readme.txt auf den eigenen wordpress.org-Benutzernamen setzen.
2. Banner und Screenshots erzeugen, siehe .wordpress-org/README.md.
3. Optional den vollständigen GPL-2.0-Text in LICENSE ablegen (https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt).
4. Das Plugin mit dem offiziellen Plugin Check prüfen lassen.
5. languages/regatta-results.pot neu erzeugen – die Vorlage wird derzeit von Hand gepflegt und ist gegenüber dem Quelltext unvollständig.

Nach der Freigabe werden Übersetzungen über translate.wordpress.org gepflegt; die mitgelieferte .mo wird dann von den Sprachpaketen überschrieben, was gewollt ist.

Übersetzungen

WordPress liest die kompilierte .mo, nicht die .po. Wer eine übersetzbare Zeichenkette im Quelltext ändert, ändert damit die msgid – greift die Übersetzung nicht mehr, steht plötzlich die englische Quelle auf einer deutschen Website. Wie die .mo neu gebaut und das Ergebnis geprüft wird, steht in tools/README.md.

Tests

Alle drei laufen ohne WordPress und ohne Datenbank:

php tests/test-fixtures.php   # Validator, Formatter, Zustände, Aktualisierungstakt
php tests/test-races.php      # Auswahl und Sortierung der Ausschreibung
php tests/test-links.php      # Links, Spaltenüberschriften, Stand der Regatta

Zusammen 149 Prüfungen. test-fixtures.php schickt die Original-Fixtures der Zeitnahme durch Validator und Formatter – genau dieser Test hat die starlist/startlist-Abweichung aufgedeckt. test-links.php hält den Fehler fest, bei dem die Links nach einer Live-Aktualisierung auf die JSON-Antwort zeigten statt auf die Seite.

Stand

Version 1.3.1, im Betrieb gegen eine echte Aquarius-Instanz erprobt. Noch offen: die Bedeutung der state-Zahlen (siehe oben), Screenshots fürs Verzeichnis, Gutenberg-Block, CSV/PDF-Export.

Lizenz

GPL-2.0-or-later.