aistea/aistea-flippingbook

Client-side PDF flipbook content element for TYPO3 v14.

The extension is built for broad server compatibility:

• no server-side PDF conversion
• no Imagick or Ghostscript dependency
• no runtime shell commands
• local vendor assets only

Features

• custom content element Aistea FlippingBook
• PDF source via FAL
• optional cover image
• desktop flipbook powered by pdf.js + StPageFlip
• mobile fallback with incremental scroll loading
• optional toolbar actions for fullscreen and download
• configurable viewer width, height, start page, theme and cover mode

Installation

1. Require or update the package:

composer update aistea/aistea-flippingbook

2. Apply TYPO3 database schema changes:

vendor/bin/typo3 database:updateschema "*.add,*.change"

3. Clear TYPO3 caches:

vendor/bin/typo3 cache:flush

4. Ensure the site includes the extension set FlippingBook.

Required vendor assets

The extension expects local browser builds at these paths:

• Resources/Public/Vendor/pdfjs/pdf.min.mjs
• Resources/Public/Vendor/pdfjs/pdf.worker.min.mjs
• Resources/Public/Vendor/stpageflip/stpageflip.min.js
• Resources/Public/Vendor/stpageflip/stpageflip.css

The current package already references these files directly. If one of them is missing, the frontend falls back to a notice plus direct PDF link.

Backend usage

1. Create a new content element: Aistea FlippingBook
2. Select the PDF in PDF document
3. Optionally add a cover image
4. Adjust viewer settings only if the default output is not sufficient

Main fields

• PDF document The source file rendered by the viewer.
• Viewer width Base desktop width in pixels. Larger values improve sharpness but cost more performance.
• Viewer height Base desktop height in pixels.
• Start page First page opened in the viewer.
• Use cover mode Treats first and last page as hard covers for more realistic page turning.
• Mobile mode Controls small-screen behavior.
• Theme Shell styling around the viewer.
• Shadow strength Visual intensity of the viewer frame and stage.

Recommended defaults

• Viewer width: 1200
• Viewer height: 760
• Use cover mode: enabled
• Mobile mode: scroll
• Theme: auto or dark

Frontend behavior

Desktop

• the PDF is rendered to page images with pdf.js
• StPageFlip handles the page turning interaction
• only nearby pages are rendered initially to keep startup lighter

Mobile

• default mode is scroll
• pages are appended incrementally in small batches
• this avoids reserving space for the whole PDF at once
• flip mode is still available if a book-like interaction is preferred

Performance notes

• very large PDFs still cost client-side memory and CPU
• higher width and height values increase render time
• scroll is the safest mobile mode for long documents
• desktop flip mode is best suited for brochures, presentations and shorter publications

Troubleshooting

Viewer shell appears, but no pages render

Check:

• PDF file exists and is publicly reachable
• pdf.min.mjs and pdf.worker.min.mjs are present
• stpageflip.min.js and stpageflip.css are present
• TYPO3 caches were flushed after deployment

Only a direct PDF link is shown

One or more frontend vendor assets are missing or failed to load.

Mobile shows a long empty area

This usually means stale JS/CSS is still cached. Flush TYPO3 caches and hard reload the browser. The current implementation appends mobile pages incrementally instead of creating the full placeholder stack up front.

First cover page looks clipped while turning

Enable Use cover mode. The extension marks the first and last page as hard cover pages for StPageFlip.

Technical notes

• Namespace: Aistea\AisteaFlippingbook
• Extension key: aistea_flippingbook
• CType: aisteaflippingbook_book

Limitations

• client-side rendering is not ideal for extremely large PDFs
• there is no text search or full PDF.js default viewer UI
• the toolbar is intentionally compact and custom

Future improvements

• custom backend preview renderer
• editor presets instead of raw width/height values
• page thumbnails
• deep-linking to a specific page
• analytics events for page turns