BRV Tabellen für WordPress

Ein WordPress-Plugin zur Darstellung öffentlich abrufbarer Ligatabellen des Bayerischen Ringer-Verbandes.

Das Plugin ruft die Tabellen serverseitig aus der BRV-Ringerdatenbank ab, bereitet sie für WordPress auf und bindet sie über konfigurierbare Shortcodes ein. Ein ausgewählter Verein kann in der Tabelle farblich hervorgehoben werden.

Hinweis: Dieses Projekt ist kein offizielles Plugin des Bayerischen Ringer-Verbandes. „BRV“ und die auf der Quellseite dargestellten Daten gehören den jeweiligen Rechteinhabern.

Funktionen

• Verwaltung beliebig vieler Tabellen-Einbindungen
• Auswahl von Liga, Staffel, Saison und Klasse
• Abruf der Mannschaften aus der gewählten Liga
• Auswahl und farbliche Hervorhebung eines Vereins
• Einbindung über WordPress-Shortcodes
• responsive Tabelle mit horizontalem Scrollen auf kleinen Displays
• konfigurierbares Cache-Intervall
• manueller Aktualisierungsbutton
• letzter erfolgreicher Stand als Ausfallsicherung
• optionaler Titel sowie Quellen- und Aktualisierungshinweis
• Berechtigungs- und Nonce-Prüfungen in der Administration
• serverseitiger Abruf über die WordPress HTTP API

Systemanforderungen

Komponente	Mindestanforderung	Hinweis
WordPress	6.2 oder neuer	Multisite wird derzeit nicht gesondert unterstützt oder getestet.
PHP	7.4 oder neuer	PHP 8.1 oder neuer wird für neue Installationen empfohlen.
PHP-Erweiterung	DOM/XML	DOMDocument und DOMXPath müssen verfügbar sein.
Serververbindung	HTTPS ausgehend	Der Server muss https://www.brv-ringen.de erreichen können.
Browser	modernes JavaScript	Wird in der Administration für das Laden der Vereinsauswahl benötigt.

Für Besucher ist kein JavaScript erforderlich, um die bereits serverseitig erzeugte Tabelle zu sehen. Die Anforderungen betreffen die WordPress-Installation und den Webserver; es werden keine Node.js-, Composer- oder Build-Werkzeuge für den normalen Plugin-Betrieb benötigt.

Die Mindestversion WordPress 6.2 ist im Haupt-Plugin-Header hinterlegt. WordPress kann dadurch bereits vor der Aktivierung auf eine zu alte Installation hinweisen.

Installation über WordPress

1. Die aktuelle ZIP-Datei herunterladen.
2. In WordPress Plugins → Neues Plugin → Plugin hochladen öffnen.
3. Die ZIP-Datei auswählen und installieren.
4. BRV Tabellen aktivieren.
5. Einstellungen → BRV Tabellen öffnen.

Manuelle Installation

Den Ordner brv-tabellen nach wp-content/plugins/ kopieren und das Plugin anschließend in der WordPress-Administration aktivieren.

Erste Schritte

Bei der Aktivierung legt das Plugin zwei Beispielkonfigurationen an:

[brv_tabelle id="regionalliga"]
[brv_tabelle id="gruppenoberliga-nord"]

Diese Konfigurationen sind für folgende Wettbewerbe vorbereitet:

ID	Wettbewerb	Markierter Verein
regionalliga	Regionalliga	TSV Burgebrach
gruppenoberliga-nord	Gruppenoberliga Nord	TSV Burgebrach II

So wird eine Tabelle eingebunden:

1. Unter Einstellungen → BRV Tabellen eine Einbindung erstellen oder öffnen.
2. Liga, Staffel, Saison und Klasse auswählen.
3. Vereine der Liga laden anklicken.
4. Den hervorzuhebenden Verein auswählen.
5. Farben und Cache-Intervall festlegen.
6. Die Einbindung speichern.
7. Den angezeigten Shortcode in eine Seite, einen Beitrag oder einen Shortcode-Block einfügen.

Shortcode

[brv_tabelle id="regionalliga"]

Das Attribut id verweist auf die in der Administration vergebene Einbindungs-ID. Unbekannte IDs erzeugen für normale Besucher keine Ausgabe. Administratoren sehen stattdessen einen Hinweis.

Konfigurationsfelder

Feld	Beschreibung
Bezeichnung	Öffentliche Überschrift der Tabelle
Einbindungs-ID	Eindeutiger Wert für den Shortcode
Liga	Beispielsweise Regionalliga oder Gruppenoberliga
Staffel	Keine, Nord oder Süd
Saison	Vierstelliges Jahr oder auto
Klasse	Männer oder Schüler
Hervorgehobener Verein	Mannschaft, deren Tabellenzeile markiert wird
Markierungsfarben	Hintergrund- und Textfarbe der markierten Zeile
Cache	Zeit bis zum nächsten automatischen Abruf
Anzeige	Titel und Quellenangabe ein- oder ausblenden

Bei auto verwendet das Plugin das aktuelle Kalenderjahr als Saison.

Datenabruf und Cache

Die BRV-Ringerdatenbank stellt derzeit keine öffentlich dokumentierte JSON-API bereit. Das Plugin lädt deshalb die öffentlich erreichbare HTML-Ligaseite und sucht semantisch nach der Überschrift „Tabelle“ und der unmittelbar folgenden HTML-Tabelle.

Die Antwort wird in ein neutrales Datenformat überführt. Fremde Skripte, Styles oder sonstige Seitenelemente werden nicht übernommen. Inhalte der Tabellenzellen werden vor der Ausgabe maskiert.

Erfolgreich geladene Daten werden als WordPress-Transient gespeichert. Zusätzlich merkt sich das Plugin den letzten erfolgreichen Stand ohne Ablaufdatum. Ist der BRV vorübergehend nicht erreichbar, kann daher weiterhin die zuletzt geladene Tabelle mit einem entsprechenden Hinweis angezeigt werden.

Datenschutz

Der Tabellenabruf erfolgt vom WordPress-Server zum Server des BRV. Der Browser eines Websitebesuchers verbindet sich für die Tabellendarstellung nicht direkt mit dem BRV. Es werden keine BRV-Skripte, Cookies oder Tracking-Komponenten in die WordPress-Seite eingebettet.

Standardmäßig zeigt das Plugin unter der Tabelle einen Link zur Quelle und den Zeitpunkt des letzten erfolgreichen Abrufs an.

Fehlerbehebung

„Die PHP-DOM-Erweiterung ist auf dem Webserver nicht verfügbar“

Beim Hostinganbieter die PHP-Erweiterungen dom beziehungsweise php-xml aktivieren lassen.

„Der BRV antwortete mit HTTP-Status …“

Den Abruf später erneut versuchen und prüfen, ob der Hostinganbieter ausgehende HTTPS-Verbindungen erlaubt. Unter Einstellungen → BRV Tabellen kann mit Jetzt aktualisieren ein neuer Abruf ausgelöst werden.

Es werden keine Vereine geladen

• Liga, Staffel, Saison und Klasse kontrollieren.
• Prüfen, ob die entsprechende Saison beim BRV bereits angelegt wurde.
• Vereine der Liga laden erneut anklicken.
• Die zugehörige Tabelle direkt auf der BRV-Website öffnen.

Die Tabelle wird nicht mehr erkannt

Das Plugin ist auf die öffentlich ausgegebene HTML-Struktur des BRV angewiesen. Wenn der BRV diese wesentlich verändert, muss gegebenenfalls die Methode parse_table() angepasst werden.

Projektstruktur

brv-tabellen/
├── assets/
│   └── brv-tabellen.css
├── brv-tabellen.php
├── build.ps1
├── LICENSE
└── README.md

• brv-tabellen.php: Plugin-Logik, Administration, Abruf und Shortcode
• assets/brv-tabellen.css: responsive Frontend-Darstellung
• README.md: zentrale Dokumentation für GitHub und das Plugin-Paket
• LICENSE: vollständiger Lizenztext
• build.ps1: erzeugt das installierbare ZIP-Paket

Installationspaket erstellen

Die ZIP-Datei ist ein erzeugtes Release-Artefakt und gehört nicht zum eigentlichen Quellcode. Sie wird deshalb nicht dauerhaft im Repository versioniert. Unter Windows kann das Installationspaket im Repository-Stammverzeichnis so gebaut werden:

.\build.ps1

Das Skript liest die Versionsnummer aus dem Plugin-Header und erzeugt anschließend:

dist/brv-tabellen-1.0.0.zip

Die ZIP-Datei enthält einen übergeordneten Ordner brv-tabellen, sodass sie direkt unter Plugins → Neues Plugin → Plugin hochladen installiert werden kann. Für eine GitHub-Veröffentlichung sollte diese Datei an ein GitHub Release angehängt werden.

Automatische Builds mit GitHub Actions

Der Workflow .github/workflows/build-release.yml übernimmt den Paketbau auf GitHub:

• Jeder Push auf main erzeugt ein installierbares ZIP als Workflow-Artefakt.
• Pull Requests gegen main werden ebenfalls gebaut.
• Ein Tag im Format v1.0.0 erzeugt zusätzlich ein dauerhaftes GitHub Release.
• Vor einem Release wird geprüft, ob Tag und Version: im Plugin-Header übereinstimmen.
• Der Workflow kann im Reiter Actions auch manuell gestartet werden.

Workflow-Artefakte sind für Tests gedacht und werden nach 14 Tagen gelöscht. Sie stehen auf der Detailseite des jeweiligen Laufs im Bereich Artifacts zum Download bereit. Release-Dateien bleiben dagegen unter Releases verfügbar, bis das Release gelöscht wird.

Version 1.0.0 veröffentlichen

Zuerst müssen alle Änderungen auf main committed und gepusht sein. Danach wird der Release-Tag gesetzt und übertragen:

git tag -a v1.0.0 -m "BRV Tabellen 1.0.0"
git push origin v1.0.0

Der Tag-Push startet den Workflow. Nach erfolgreichem Abschluss erscheint unter Releases automatisch das Release BRV Tabellen v1.0.0 mit der Datei brv-tabellen-1.0.0.zip.

Für eine neue Version müssen zuerst die Versionsnummer in brv-tabellen.php und die Dokumentation angepasst und committed werden. Erst danach sollte der entsprechende Tag, beispielsweise v1.1.0, erstellt werden.

GitHub Packages

GitHub Packages wird für dieses Projekt nicht benötigt. Es ist vor allem eine Paket-Registry für Formate wie npm, Maven, NuGet oder Container-Images. Eine installierbare WordPress-ZIP gehört als Datei an ein GitHub Release; kurzlebige Testpakete gehören zu den Workflow-Artefakten.

Entwicklung

Für lokale Tests empfiehlt sich eine aktuelle WordPress-Testinstallation mit aktiviertem Debug-Modus:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Vor einem Release sollten mindestens folgende Fälle geprüft werden:

• Neuinstallation und Aktivierung
• Bearbeiten der beiden Beispielkonfigurationen
• Laden der Mannschaften für Regionalliga und Gruppenoberliga Nord
• Einbindung beider Shortcodes auf einer Seite
• mobile Darstellung
• Cache-Aktualisierung
• Verhalten bei nicht erreichbarem BRV-Server
• Verhalten bei ungültiger Einbindungs-ID

Sicherheit

• Administrationsaktionen erfordern die WordPress-Berechtigung manage_options.
• Schreibende Aktionen und AJAX-Aufrufe sind mit WordPress-Nonces geschützt.
• Externe URLs werden vom Plugin selbst erzeugt und mit wp_safe_remote_get() abgerufen.
• Entfernte HTML-Inhalte werden nicht unverändert ausgegeben.
• Tabellenwerte werden mit WordPress-Escaping-Funktionen maskiert.

Sicherheitsprobleme sollten nicht als öffentliches GitHub-Issue veröffentlicht werden. Dafür sollte im Repository eine private Kontaktmöglichkeit hinterlegt werden.

Bekannte Einschränkungen

• Es existiert keine bekannte offizielle BRV-API.
• Änderungen an der HTML-Struktur des BRV können den Import beeinflussen.
• Die Verfügbarkeit und Richtigkeit der Daten liegt beim BRV.
• Die Vereinsauswahl funktioniert erst, wenn die betreffende Ligatabelle beim BRV erreichbar ist.
• Das Plugin importiert ausschließlich Tabellen; Ergebnisse einzelner Kämpfe sind in Version 1.0.0 nicht enthalten.

Mitwirken

Fehlerberichte und Pull Requests sind willkommen. Ein Fehlerbericht sollte nach Möglichkeit enthalten:

• WordPress- und PHP-Version
• gewählte Liga, Staffel und Saison
• genaue Fehlermeldung
• Schritte zum Reproduzieren

Keine Zugangsdaten, personenbezogenen Daten oder vollständigen Server-Logs in öffentliche Issues aufnehmen.

Lizenz

Der Plugin-Code steht unter der GNU General Public License v3.0 oder neuer.

Die Lizenz gilt nur für den Plugin-Code. Sie überträgt keine Rechte an Namen, Logos, Inhalten oder Daten des Bayerischen Ringer-Verbandes.

Haftungsausschluss

Dieses Plugin wird ohne Gewährleistung bereitgestellt. Für die Vollständigkeit, Aktualität oder Verfügbarkeit der extern bezogenen Tabellen wird keine Garantie übernommen.