⬇️ Install package: OMP 3.5 — or browse all Releases.

▶️ Live demo: Editora UEMG — book with a PDF format

A page-turning reading mode for PDF monographs, sitting beside the native PDF viewer instead of replacing it: the reader gets a Flip through button on the book page and a full-viewport flipbook, and can go back to the ordinary PDF at any time.

Developed and maintained by OJSBR. See the Credits & authorship section below.

• Adds a Flip through button next to every PDF on the book and chapter pages — or, if the press prefers, in place of the PDF link, with the flipbook label or with the label of the PDF link itself.
• Opens a full-viewport reader with a two-page spread, page-turn animation, drag and keyboard navigation.
• Zoom from 50% to 250%, full screen, and a link back to the ordinary PDF view.
• Re-lays the book out on window resize and orientation change.

It never replaces the native viewer. The flipbook paints pages to canvas: there is no text selection, no search and no screen-reader access. That is exactly why it is an alternative and never the default — out of the box the PDF viewer remains the primary click, and even when a press puts the button in place of the PDF link, the viewer and the download stay one click away from View as PDF in the flipbook.

Upload the package in Settings → Website → Plugins → Upload A New Plugin, or clone the branch into plugins/generic/pdfFlipbook. Then enable it in the plugin list.

Settings → Website → Plugins → PDF Flipbook Reader → Settings, per press:

The link is replaced in the browser, like the button is added: OMP has no hook inside the download link template. Without JavaScript the page keeps the ordinary PDF link.

Coexistence. The same reader URL serves both modes; the reader=flipbook parameter decides (leitor=folhear, the parameter of releases before 0.4.0.0, still works). The plugin registers on CatalogBookHandler::view at normal sequence — that is, before pdfJsViewer, which registers late — and aborts the hook only when it really takes over. Without the parameter it does nothing and the native viewer runs untouched. No core patching, and the PKP plugin stays enabled.

Cache of the plugin's files. PKP appends ?v={OMP version} to asset URLs, which does not change when only a plugin is updated. The button script, its stylesheet and every file of the reader carry ?v={plugin version} instead, so an update reaches readers' browsers at once.

Rendering. StPageFlip does not read PDF. PDF.js rasterises each page to a canvas and StPageFlip mounts those as sheets. Both libraries are vendored in lib/ — no CDN: PDF.js 3.11.174 and StPageFlip. PDF.js is always called with isEvalSupported: false, which closes CVE-2024-4367 (script run from a crafted font) for that version.

Memory. Pages are drawn on demand (current spread ± 2) and the canvas cache is capped at 14 sheets; evicted pages release their bitmap. Empty divs are cheap, rasterised pages are not — that is where the ceiling had to be. Above 1000 pages the reader declines and points at the PDF viewer.

Two behaviours of StPageFlip worth knowing, both learned the hard way:

• destroy() removes the container itself from the DOM, not just its content. Zoom, resize and full screen all remount the book (the library takes width/height only in the constructor), so the container is recreated on every mount. Without that the reader mounted into an orphan node and the screen went blank with no console error.
• It moves the page elements into its own structure rather than cloning them. The plugin does not rely on that: it looks the sheet up from the book root, falls back to the whole document, and warns once — so a future version that starts cloning degrades with a message instead of silently drawing nothing.

• PHPUnit (tests/*Test.php, on PKP\tests\PKPTestCase, 25 tests): when the flipbook takes over (only a PDF, only with the parameter, never EPUB, audio or an empty type), links with the parameter of earlier releases, the reader page (core footer hook kept, no inline script, every URL escaped, every file stamped with the plugin version), PDF.js never evaluating code from the file, the settings (posted through the form, read back from plugin_settings, and handed to the page — an unticked box turns a setting off, keeping the label alone changes nothing), the plugin classes against the installed PKP, the 38 translations and the templates. From the installation root:

  lib/pkp/lib/vendor/bin/phpunit --configuration lib/pkp/tests/phpunit.xml --no-coverage "$PWD/plugins/generic/pdfFlipbook/tests"

• Cypress (cypress/tests/functional/PdfFlipbook.cy.js, run by pkp-github-actions on OMP on every push): enables the plugin, saves the settings in the modal and reads them back. With pdfBookPage (the path of a book page with an available PDF format) it also checks the button next to the ordinary PDF link, pages actually rendering, navigation, zoom (it destroys and rebuilds StPageFlip, which once left a blank screen with no console error), the way back, a link with leitor=folhear, and the PDF link replaced by the button (with each label, other formats kept) and then put back. Those fail with the hook off.

  npx cypress run --config specPattern='plugins/generic/pdfFlipbook/cypress/tests/functional/*.cy.js' \
    --env contextPath=<press>,adminUser=<user>,adminPassword=<password>,pdfBookPage=index.php/<press>/catalog/book/1

• Verified on OMP 3.5.0.5 with a published book.

Tests are kept in the repository and are not part of the release package.

• OJSBR — https://ojsbr.com — plugin design, implementation and maintenance.
• StPageFlip by Nodlik — MIT — the page-turn engine.
• PDF.js by Mozilla — Apache 2.0 — PDF rasterisation.
• Public Knowledge Project (PKP) — Open Monograph Press and the plugin API.

Generative AI (Claude, by Anthropic) was used to write and run tests, improve the code and bring it in line with PKP standards. Every change is reviewed and tested by OJSBR, which is responsible for the published releases.

Issues and pull requests are welcome — see CONTRIBUTING.md and CODE_OF_CONDUCT.md. Target the branch matching your OMP version.

GNU GPL v3 — see LICENSE and docs/COPYING. Vendored libraries keep their own licences (MIT for StPageFlip, Apache 2.0 for PDF.js).

Modo de leitura folheável para PDF de livros, que fica ao lado do visualizador nativo em vez de substituí-lo: o leitor ganha um botão Folhear na página do livro e um flipbook em tela cheia, e pode voltar ao PDF comum a qualquer momento.

▶️ Demonstração: Editora UEMG — livro com formato PDF

• Botão Folhear ao lado de cada PDF nas páginas do livro e dos capítulos — ou, se a editora preferir, no lugar do link do PDF, com o rótulo do folhear ou com o rótulo do próprio link do PDF.
• Leitor em tela cheia com dupla de páginas, animação de virada, arrasto e teclado.
• Zoom de 50% a 250%, tela cheia e link de volta para o PDF comum.
• Recalcula o tamanho das folhas ao redimensionar a janela ou girar o aparelho.

Ele nunca substitui o visualizador nativo. O flipbook desenha as páginas em canvas: não há seleção de texto, busca nem leitura por leitor de tela. É por isso que ele é alternativa e nunca o padrão — de fábrica o PDF continua sendo o clique principal e, mesmo quando a editora põe o botão no lugar do link do PDF, o visualizador e o download ficam a um clique, pelo Ver como PDF do folhear.

Envie o pacote em Configurações → Website → Plugins → Enviar um novo plugin, ou clone a branch em plugins/generic/pdfFlipbook. Depois ative na lista de plugins.

Configurações → Website → Plugins → Leitor Folhear (flipbook) de PDF → Configurações, por editora:

A troca é feita no navegador, como o botão já era: o OMP não tem hook dentro do template do link de download. Sem JavaScript, a página mantém o link comum do PDF.

Convivência. O mesmo endereço serve os dois modos; quem decide é o parâmetro reader=flipbook (o leitor=folhear das versões anteriores à 0.4.0.0 continua valendo). O plugin se registra no hook CatalogBookHandler::view em sequência normal — antes do pdfJsViewer, que é tardio — e só interrompe o hook quando realmente assume. Sem o parâmetro, não faz nada e o visualizador nativo segue intacto. Sem patch no núcleo e sem desligar o plugin do PKP.

Cache dos arquivos do plugin. O PKP acrescenta ?v={versão do OMP} aos endereços dos arquivos, e isso não muda quando só o plugin é atualizado. O script do botão, a folha de estilo e todos os arquivos do leitor levam ?v={versão do plugin}, para a atualização chegar ao navegador do leitor na hora.

Renderização. O StPageFlip não lê PDF: o PDF.js rasteriza cada página em canvas e o StPageFlip monta as folhas. As duas bibliotecas são vendorizadas em lib/, sem CDN: PDF.js 3.11.174 e StPageFlip. O PDF.js é sempre chamado com isEvalSupported: false, o que fecha a CVE-2024-4367 (script executado a partir de fonte forjada) nessa versão.

Memória. As páginas são desenhadas sob demanda (a dupla atual ± 2) e o cache de canvas tem teto de 14 folhas, liberando o bitmap das descartadas. div vazia é barata; página rasterizada não é — o teto real tinha de ser aí. Acima de 1000 páginas o leitor recusa e aponta o visualizador de PDF.

Dois comportamentos do StPageFlip que valem saber, os dois aprendidos na marra:

• O destroy() remove o próprio contêiner do DOM, não só o conteúdo. Zoom, redimensionamento e tela cheia remontam o livro (a biblioteca só aceita largura/altura no construtor), então o contêiner é recriado a cada montagem. Sem isso, o leitor montava num nó órfão e a tela ficava vazia sem um erro no console.
• Ele move as folhas para a estrutura dele em vez de cloná-las. O plugin não depende disso: procura a folha a partir da raiz do livro, cai para o documento inteiro e avisa uma vez — assim, uma versão futura que passe a clonar degrada com recado em vez de desenhar nada em silêncio.

PHPUnit em tests/ (sobre PKP\tests\PKPTestCase, 25 testes) e Cypress em cypress/tests/functional/ (rodado pelo pkp-github-actions no OMP a cada push), com os comandos da seção em inglês. A suíte cobre quando o folhear assume o arquivo, os links com o parâmetro das versões anteriores, a página do leitor (hook de rodapé do núcleo, nenhum script inline, URLs escapadas, arquivos com a versão do plugin), o PDF.js sem executar código do arquivo, as configurações (enviadas pelo formulário, lidas de volta de plugin_settings e entregues à página — caixa desmarcada desliga, manter o rótulo sozinho não muda nada), as classes do plugin contra o PKP instalado, as 38 traduções e os templates. O Cypress salva as configurações no modal e as lê de volta; com pdfBookPage, confere o botão ao lado do link de PDF, as páginas desenhadas, a navegação, o zoom, o link de voltar e o link do PDF substituído pelo botão (com cada rótulo) e depois restaurado.

Verificado no OMP 3.5.0.5 com um livro publicado.

Os testes ficam no repositório e não fazem parte do pacote da release.

• OJSBR — https://ojsbr.com — concepção, implementação e manutenção.
• StPageFlip, de Nodlik — MIT — o motor de virada de página.
• PDF.js, da Mozilla — Apache 2.0 — a rasterização do PDF.
• Public Knowledge Project (PKP) — o Open Monograph Press e a API de plugins.

Foi usada IA generativa (Claude, da Anthropic) para escrever e rodar testes, melhorar o código e alinhá-lo aos padrões da PKP. Toda mudança é revisada e testada pela OJSBR, que responde pelas releases publicadas.

GNU GPL v3 — veja LICENSE e docs/COPYING. As bibliotecas vendorizadas mantêm suas próprias licenças (MIT no StPageFlip, Apache 2.0 no PDF.js).