Jürgen MummertandClaude Opus 5
204fee73f5
New content element option "Vollbild-Schaltfläche anzeigen" (on by default). The button only appears once the browser confirms it exposes the Fullscreen API for ordinary elements -- iOS Safari offers it for video only, so there it stays hidden rather than presenting a control that cannot work. Fitting the book to the screen needed the layout to become height-aware. Page size was derived from width alone, which at screen width puts an A4-proportioned page well below the bottom of the viewport. In fullscreen the page now fits to the available height and the narrower book is centred; pages re-render at the new size through the existing generation-stamped path. The height fit writes a max-width onto the stage, so in fullscreen the available width is measured on the parent instead -- measuring the element we just constrained would oscillate. Verified stable across repeated samples. The resize handler body moved into relayout(), shared with the fullscreen toggle. destroy() leaves fullscreen first so the browser is not left holding a node that is about to go away. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
95 lines
3.5 KiB
Markdown
95 lines
3.5 KiB
Markdown
# Flipbook Bundle (Contao 5.7)
|
||
|
||
Contao Inhaltselement zum Darstellen von PDFs als blätterbares Flipbook.
|
||
|
||
## Features
|
||
|
||
- Reines JavaScript (ES Modules), keine Build-Kette
|
||
- `pdfjs-dist` für PDF-Rendering in `<canvas>`
|
||
- `flipbook-js` für den Blättereffekt
|
||
- Lazy Rendering: 2–4 Seiten sofort, Rest on-demand
|
||
- Automatisches Freigeben weit entfernter Seiten, damit der Speicher auch bei
|
||
mehrhundertseitigen PDFs beschränkt bleibt
|
||
- Optionales Aufteilen von Doppelseiten in linke und rechte Einzelseite
|
||
- Optionale Vor-/Zurück-Navigation, optionaler Blättersound
|
||
- Optionaler Vollbildmodus, der die Seitengröße an die Bildschirmhöhe anpasst
|
||
- Tastatursteuerung (Pfeiltasten) und Touch-Swipe
|
||
- Responsive Breite mit beibehaltenem Seitenverhältnis
|
||
- Frontend-Texte übersetzbar (DE/EN mitgeliefert)
|
||
|
||
## Installation (VCS oder Paket)
|
||
|
||
```bash
|
||
composer require mummert/flipbook-bundle
|
||
```
|
||
|
||
## Inhaltselement im Backend
|
||
|
||
Elementtyp: `Blätterbares PDF`
|
||
|
||
Felder:
|
||
|
||
- `PDF-Datei` (fileTree / UUID)
|
||
- `Initial geladene Seiten` (2, 3 oder 4)
|
||
- `Startmodus` (zentriert oder als Doppelseite)
|
||
- `Doppelseiten aufteilen` (optional)
|
||
- `Navigation anzeigen` (optional)
|
||
- `Vollbild-Schaltfläche anzeigen` (optional)
|
||
- `Blättersound abspielen` (optional)
|
||
|
||
## Hinweise
|
||
|
||
- Das Inhaltselement rendert PDF-Seiten als `<canvas>` innerhalb von `.c-flipbook__page`.
|
||
- Alle benötigten Open-Source-Dateien liegen lokal im Bundle; es gibt keine
|
||
Requests an externe CDNs.
|
||
- CSS und Modul-Script werden vom Controller über `$GLOBALS['TL_HEAD']`
|
||
registriert und landen damit einmal pro Seite im Head — auch wenn mehrere
|
||
Flipbooks auf derselben Seite stehen.
|
||
- Asset-Pfade werden zur Laufzeit aus `import.meta.url` abgeleitet. Das Bundle
|
||
funktioniert dadurch auch, wenn Contao in einem Unterverzeichnis läuft.
|
||
- `vendor/cmaps/` und `vendor/standard_fonts/` werden von PDF.js nur bei Bedarf
|
||
nachgeladen (CID-Encodings bzw. nicht eingebettete Standard-Fonts).
|
||
- Siehe `THIRD_PARTY_LICENSES.md` für Abhängigkeiten und `licenses/` für die
|
||
Lizenztexte.
|
||
|
||
### Barrierefreiheit
|
||
|
||
Canvas-Inhalte sind für Screenreader und die Seitensuche des Browsers nicht
|
||
zugänglich. Das Element gibt deshalb pro Seite ein `aria-label` aus und blendet
|
||
unter dem Flipbook einen Download-Link auf die Original-PDF ein — das ist die
|
||
gleichwertige Alternative im Sinne von WCAG. Wird der Link per CSS ausgeblendet,
|
||
entfällt diese Gleichwertigkeit.
|
||
|
||
### Vollbild
|
||
|
||
Die Schaltfläche wird erst eingeblendet, wenn der Browser die Fullscreen-API für
|
||
normale Elemente anbietet. Safari auf dem iPhone gehört nicht dazu — dort bleibt
|
||
sie verborgen, statt eine Funktion anzubieten, die nicht arbeiten kann.
|
||
|
||
Im Vollbild wird die Seitenhöhe an den Bildschirm angepasst und das Buch
|
||
zentriert; ohne das wäre eine A4-Seite bei Bildschirmbreite deutlich höher als
|
||
der Viewport. Die Seiten werden dabei in der neuen Größe neu gerendert.
|
||
|
||
### Geschützte Ordner
|
||
|
||
Contao liefert Dateien unter `files/` nur aus, wenn der Ordner öffentlich
|
||
freigegeben ist. Liegt die gewählte PDF in einem geschützten Ordner, lädt das
|
||
Flipbook nicht. Der Controller prüft nur, ob die Datei überhaupt auf der Platte
|
||
existiert — die Freigabe selbst muss im Dateimanager gesetzt sein.
|
||
|
||
### JavaScript-API
|
||
|
||
Für AJAX- oder Turbo-getriebene Seiten:
|
||
|
||
```js
|
||
window.MummertPdfFlipbook.scan(); // neue Elemente initialisieren
|
||
window.MummertPdfFlipbook.destroyAll(); // Instanzen abbauen, Speicher freigeben
|
||
```
|
||
|
||
## Release
|
||
|
||
```bash
|
||
git tag v1.0.0
|
||
git push origin v1.0.0
|
||
```
|