From bfc9bd61b581a46e6b3de0ce39868c3015095636 Mon Sep 17 00:00:00 2001 From: Terranom674 Date: Sun, 16 Aug 2026 20:59:10 +0200 Subject: [PATCH] Update README for current Bratonien Tools features --- README.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 122 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 4768134..fc159c4 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,144 @@ # Piwigo Bratonien Tools -Eigene, modular aufgebaute Administrationswerkzeuge fuer die Bratonien-Piwigo-Installation. +Modular aufgebautes Piwigo-Plugin mit erweiterten Werkzeugen fuer Administration, Bildverarbeitung und Frontend-Funktionen. -## Ziel +Das Projekt ist aus der Bratonien-Piwigo-Installation entstanden, wird aber bewusst so entwickelt, dass die einzelnen Funktionen moeglichst neutral und auch ausserhalb dieser Installation nutzbar bleiben. -Das Plugin ist bewusst als Werkzeugkasten aufgebaut. Neue Funktionen werden als getrennte Tools implementiert und anschliessend zentral registriert. Die Admin-Oberflaeche stellt registrierte Tools automatisch dar. +Aktuelle Plugin-Version: **0.11.2** -## Aktuelles Tool: Bildcache leeren +## Funktionsumfang -Der One-Click-Button **Bildcache leeren** entfernt alle von Piwigo erzeugten Dateien unter `_data/i/`, mit Ausnahme von `index.htm`. +### Bildcache -Damit werden unter anderem geloescht: +- Piwigo-Bildcache gezielt leeren +- vorhandene Bildderivate neu erzeugen +- Cache-Aufbau als Worker-Prozess starten und abbrechen +- Worker-Einstellungen verwalten +- Originalbilder bleiben unangetastet -- Standard-Bildderivate -- Vorschaubilder -- gdThumb-Custom-Derivate (`cu_*`) -- weitere von Piwigo oder Plugins dort erzeugte Bildvarianten +### Wasserzeichenverwaltung -Originalbilder unter `galleries/` werden nicht veraendert. Piwigo erzeugt benoetigte Derivate beim naechsten Aufruf neu. +Erweiterte Wasserzeichenverwaltung als Alternative zur einfachen Piwigo-Standardkonfiguration. -Der Browsercache ist bewusst nicht Bestandteil dieses Tools. +Unter anderem vorhanden: -## Struktur +- eigene Wasserzeichendateien +- Wasserzeichenprofile +- Standardprofil +- albumbezogene Regeln +- getrennte Einstellungen fuer Positionierung und Verarbeitung +- eigener Runtime-Filter fuer Piwigo-Bildderivate +- Aktivierung und Deaktivierung der erweiterten Wasserzeichen-Engine -- `main.inc.php` - Plugin-Einstieg und Admin-Menue +Beim Aktivieren wird die bisherige Piwigo-Wasserzeichenkonfiguration gesichert und nicht dauerhaft ueberschrieben. Beim Deaktivieren kann sie wiederhergestellt werden. + +### Bilddateien & Pfade + +Verwaltung eigener Bilddateien fuer die Piwigo-Installation. + +- Upload nach `local/bratonien/assets/` +- Vorschau vorhandener Dateien +- Anzeige von Dateiname, Pfad, Abmessungen und Dateigroesse +- Dateien loeschen +- konfigurierbare PHP-Uploadgrenzen ueber `.user.ini` +- Validierung von `upload_max_filesize` und `post_max_size` + +### Oeffentliche Bildauswahl fuer Batch Downloader + +Erweitert Albumseiten um die Moeglichkeit, einzelne Bilder fuer einen Download auszuwählen. + +- Auswahlmodus direkt in der Albumansicht +- einzelne Bilder markieren +- alle Bilder auswaehlen oder Auswahl aufheben +- nur die ausgewaehlten Bilder an Batch Downloader uebergeben +- vorhandene Piwigo- und Batch-Downloader-Berechtigungen bleiben wirksam +- getrennte Freigabe fuer Gaeste, registrierte Benutzer und Gruppen + +**Abhaengigkeit:** Das Piwigo-Plugin Batch Downloader muss installiert und aktiv sein. + +Die ZIP-Erstellung wird nicht dupliziert. Bratonien Tools uebergibt lediglich die berechtigten Bild-IDs an Batch Downloader. + +### Erweiterte Bildnavigation + +Auf der Bilddetailseite werden die vorhandenen Piwigo-Image-Maps weiterverwendet und responsiv neu aufgeteilt. + +Die Bildflaeche besteht aus vier Navigationszonen: + +- links: vorheriges Bild +- rechts: naechstes Bild +- oben mittig: zurueck zur Vorschau beziehungsweise Albumansicht +- Mitte: PhotoSwipe / Vollbildansicht + +Die Zonen werden anhand der aktuell dargestellten Bildgroesse berechnet und bei Groessenaenderungen neu gesetzt. + +Fuer die sichtbaren Hover-Elemente werden neutrale CSS-Klassen bereitgestellt. Das Plugin enthaelt bewusst kein Bratonien-spezifisches Farbschema. Individuelles Branding kann ueber Theme- oder Custom-CSS erfolgen. + +Relevante Klassen: + +```css +.bratonien-picture-zones +.bratonien-picture-zone +.bratonien-picture-zone-previous +.bratonien-picture-zone-next +.bratonien-picture-zone-thumbnails +.bratonien-picture-zone-photoswipe +.bratonien-picture-zone.is-active +``` + +Die Icons verwenden vorhandene Font-Awesome-Klassen des aktiven Frontends. + +### Selbstaktualisierung + +Bratonien Tools kann den aktuellen Stand des GitHub-Repositories pruefen und sich aus der Administration heraus aktualisieren. + +Der Status wird nach Update-Pruefungen und Aktionen direkt neu eingelesen, damit die Administrationsseite nicht mit veralteten Versionsinformationen weiterarbeitet. + +## Architektur + +Das Plugin ist modular aufgebaut. Administrative Werkzeuge werden getrennt implementiert und ueber eine zentrale Registry eingebunden. Frontend-Erweiterungen liegen ebenfalls in eigenen Modulen. + +Wichtige Bestandteile: + +- `main.inc.php` - Plugin-Einstieg, Runtime-Module und Admin-Menue - `admin.php` - zentraler Admin-Controller -- `include/tool_registry.inc.php` - Registry aller verfuegbaren Werkzeuge -- `tools/` - Implementierungen einzelner Werkzeuge -- `template/admin.tpl` - gemeinsame Admin-Oberflaeche +- `include/tool_registry.inc.php` - Registry der administrativen Aktionen +- `include/public_selection.inc.php` - oeffentliche Fotoauswahl und Batch-Downloader-Anbindung +- `include/picture_navigation.inc.php` - Einbindung der erweiterten Bildnavigation +- `include/watermark_*.inc.php` - Wasserzeichen-Engine und Runtime +- `include/self_update.inc.php` - Selbstaktualisierung +- `tools/` - administrative Werkzeugmodule +- `js/` - Frontend- und Admin-JavaScript +- `css/` - strukturelles Plugin-CSS +- `template/` - Admin- und Frontend-Templates - `maintain.class.php` - Piwigo-Lifecycle -## Neues Tool hinzufuegen +## Neues administratives Tool hinzufuegen 1. Neue Implementierung unter `tools/` anlegen. 2. Datei in `include/tool_registry.inc.php` laden. -3. Tool mit Titel, Beschreibung, Button, Bestaetigung und Handler in der Registry eintragen. +3. Handler in `bratonien_tools_get_tools()` registrieren. +4. Benoetigte Darstellung in der gemeinsamen Administrationsoberflaeche ergaenzen. -Die Admin-Oberflaeche muss fuer normale One-Click-Werkzeuge nicht angepasst werden. +Funktionen sollten moeglichst eigenstaendig bleiben und keine Bratonien-spezifische Gestaltung voraussetzen. ## Sicherheit -Das Plugin prueft Administratorrechte und Piwigos CSRF-Token. Das Bildcache-Tool validiert ausserdem den Zielpfad vor dem Loeschen und greift ausschliesslich auf Piwigos `_data/i`-Verzeichnis zu. +Administrative Aktionen pruefen Piwigo-Berechtigungen und verwenden fuer schreibende Aktionen Piwigos CSRF-Schutz. + +Weitere Schutzmechanismen sind funktionsabhaengig, unter anderem: + +- Validierung von Cache- und Dateipfaden +- Filterung ausgewaehlter Bild-IDs gegen die aktuell berechtigte Bildmenge +- Beibehaltung bestehender Piwigo- und Plugin-Berechtigungen +- kontrollierte Uploadziele und Uploadgrenzen +- kein Zugriff auf Originalbilder beim Leeren des Bildcaches + +## Styling und Anpassung + +Bratonien Tools soll Funktion und Gestaltung voneinander trennen. Plugin-eigene Styles dienen daher nur der technischen Darstellung und Positionierung. + +Farben, Schatten, Hover-Effekte und individuelles Branding sollten ueber das aktive Piwigo-Theme oder Custom CSS umgesetzt werden. + +## Entwicklungsstand + +Das Plugin befindet sich weiterhin in aktiver Entwicklung. Einige Funktionen sind speziell fuer die aktuelle Piwigo-Installation entstanden und werden schrittweise weiter verallgemeinert, bevor das Projekt fuer eine breitere Nutzung vorgesehen ist.