⬇️ Install package: OMP 3.5 — or browse all Releases.
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.
| Application | Version | Branch | Plugin release |
|---|---|---|---|
| OMP | 3.5.x | stable-3_5_0 (default) |
0.3.0.3 |
- Adds a Flip through button next to every PDF on the book page.
- 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 — the PDF viewer remains the primary click.
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.
None. The plugin has no settings: it adds a button and answers one extra parameter.
Coexistence. The same reader URL serves both modes; the leitor=folhear parameter
decides. The plugin registers on CatalogBookHandler::view at normal sequence — that
is, before pdfJsViewer, which registers late — and returns true 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.
Rendering. StPageFlip does not read PDF. PDF.js rasterises each page to a canvas and StPageFlip mounts those as sheets. Both libraries are vendored — no CDN.
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, in the PKP ApplicationPlugins suite:
cd lib/pkp/tests
php ../lib/vendor/bin/phpunit --no-coverage -c phpunit.xml \
/absolute/path/to/plugins/generic/pdfFlipbook/tests6 tests / 638 assertions covering the dispatch rule (assumeArquivo) — only PDF, only
with the parameter present, never EPUB, audio or an empty type — and locale integrity:
every locale carrying every key with no empty value, no legacy locale codes, and every
key used in a template present in locale/en, since in 3.5 a missing key renders as
##key## instead of falling back to English.
Cypress, from the installation root:
npx cypress run \
--config specPattern='plugins/generic/pdfFlipbook/cypress/tests/functional/*.cy.js' \
--env contextPath=mypress,adminUsername=admin,adminPassword=secret3 specs: enabling the plugin, the flipbook button appearing next to the ordinary PDF link (never replacing it) and the pages actually rendering, and navigation, zoom and the way back to the book page. The zoom assertion exists because zooming destroys and rebuilds the StPageFlip instance — a bug once remounted it into an orphan node and left the screen blank with no console error at all.
- OJSBR — https://ojsbr.com.br — 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.
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.
| Aplicação | Versão | Branch | Release do plugin |
|---|---|---|---|
| OMP | 3.5.x | stable-3_5_0 (padrão) |
0.3.0.3 |
- Botão Folhear ao lado de cada PDF na página do livro.
- 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 — o PDF continua sendo o clique principal.
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.
Nenhuma. O plugin não tem configurações: acrescenta um botão e responde a um parâmetro.
Convivência. O mesmo endereço serve os dois modos; quem decide é o parâmetro
leitor=folhear. O plugin se registra no hook CatalogBookHandler::view em sequência
normal — antes do pdfJsViewer, que é tardio — e só devolve true 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.
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, sem CDN.
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, na suíte ApplicationPlugins da PKP:
cd lib/pkp/tests
php ../lib/vendor/bin/phpunit --no-coverage -c phpunit.xml \
/caminho/absoluto/plugins/generic/pdfFlipbook/tests6 testes / 638 asserções cobrindo a regra de despacho (assumeArquivo) e a integridade
dos 38 locales, inclusive toda chave usada em template existir no locale/en.
Cypress, a partir da raiz da instalação:
npx cypress run \
--config specPattern='plugins/generic/pdfFlipbook/cypress/tests/functional/*.cy.js' \
--env contextPath=minhaeditora,adminUsername=admin,adminPassword=senha3 specs: ligar o plugin, o botão aparecer ao lado do link de PDF (nunca no lugar dele) com as páginas realmente renderizando, e a navegação, o zoom e a volta para a página do livro. O teste de zoom existe porque o zoom desmonta e remonta o StPageFlip — um bug já remontou num nó órfão e deixou a tela em branco sem erro nenhum no console.
- OJSBR — https://ojsbr.com.br — 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.
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).