Flippy 3D Flipbook Documentation

1. Project overview

Flippy is a front-end template that showcases a 3D flipbook viewer with WebGL acceleration, built-in lightbox and drop-zone demos, and Tailwind-friendly styling. The project ships as a static site (no build toolchain required) but includes optional scripts and ES module wrappers so you can integrate it with modern bundlers.

2. System requirements

The documentation uses plain HTML/CSS/JS and can be opened directly in a browser. For local development we recommend:

3. Quick start

4. Project structure

flippy/
├─ books/                # Sample PDFs
├─ docs/                 # Documentation (this file)
├─ public/               # Static assets (icons, images)
├─ src/                  # ES modules (jQuery, Flippy, helpers)
│  ├─ flippy.js          # Core viewer logic
│  ├─ flippy.webgl.js    # WebGL rendering engine
│  ├─ flippy.pdfservice.js# PDF.js integration
│  ├─ screenfull.js      # Fullscreen helper
│  ├─ touchswipe.js      # Gesture support
│  ├─ ...                # Additional vendor modules
├─ index.html            # Landing page with live demos
├─ index.js              # Entry point that wires demos together
├─ style.css             # Tailwind compiled stylesheet
└─ package.json          # Optional scripts / metadata

5. Available scripts

The template intentionally keeps scripts minimal. Suggested commands:

6. Live demo widgets

All demos are initialized inside index.js after the core modules finish loading. Each call uses the same flippyBook API with different options.

Embedded viewer

Renders inline within the page, ideal for product tours.

jQuery("#flippyEmbedExample").flippyBook({
  pdfUrl: "./books/book.pdf",
  textLayer: true
});

Lightbox + preset viewer

jQuery("#flippyLightboxExample").flippyBook({
  pdfUrl: "./books/book02.pdf",
  textLayer: true,
  lightBox: true
});

jQuery("#flippySelectedExample").flippyBook({
  pdfUrl: "./books/book02.pdf",
  textLayer: true,
  lightBox: true
});

Both buttons target the same PDF with slightly different entry points, letting stakeholders compare triggers.

Drop zone demo

jQuery("#flippyDropZoneExample").flippyBook({
  textLayer: true,
  lightBox: true,
  dropZone: {
    enabled: true,
    statusSelector: ".flippy-dropzone-status"
  }
});

The drop zone accepts PDF files, opens them in a lightbox, and updates the status element to indicate success or validation errors.

7. Customization

Viewer options

The flippyBook initializer accepts a single configuration object. Options are additive; unspecified values fall back to sensible defaults.

Sample configuration

$("#marketingLookbook").flippyBook({
  pdfUrl: "/media/lookbook.pdf",
  lightBox: false,
  textLayer: true,
  pageShadow: false,
  autoPlay: true,
  autoPlayInterval: 7000,
  dropZone: {
    enabled: false
  },
  callbacks: {
    onReady: () => console.log("Viewer ready"),
    onPageChange: (page) => analytics.track("flipbook:page", { page })
  }
});

Common tweaks

• Swap PDFs by updating pdfUrl.
• Disable text selection (textLayer: false) for performance on graphics-heavy catalogs.
• Customize toolbar icons inside src/flippy.js (search for toolbar template strings).
• Override lightbox backdrop styles via .flippy-lightbox in style.css.

8. Branding & theming

All styling is Tailwind-compatible. To adjust colors globally, edit Tailwind variables in style.css or replace utility classes in index.html.

Dark mode persistence

The theme toggle writes the user choice to localStorage under the key flippy-theme. To change the default theme, update the inline script in index.html.

Gradient sections

Hero and drop-zone sections use layered gradient backgrounds defined directly in the markup. Adjust gradient colors to match your brand palette.

9. Embedding Flippy elsewhere

To embed the viewer into another project:

1. Copy the contents of src/, books/, style.css, and the relevant HTML snippet.
2. Ensure jquery.module.js (or your own jQuery entry) is available.
3. Call flippyBook on your target element after the DOM is ready.

<link rel="stylesheet" href="/path/to/style.css" />
<div id="myFlipbook"></div>
<script type="module">
  import $ from "/path/to/jquery.module.js";
  import "/path/to/flippy.js";
  import "/path/to/flippy.webgl.js";
  // ...other modules

  $("#myFlipbook").flippyBook({
    pdfUrl: "/documents/proposal.pdf",
    lightBox: false,
    textLayer: true
  });
</script>

10. Analytics & events

The base project does not ship analytics, but Flippy exposes callbacks via jQuery events:

• flippy:pageChange — Fired with the new page index.
• flippy:ready — Fired once the viewer is initialized.
• flippy:lightbox:open / flippy:lightbox:close — Monitor modal sessions.

$("#flippyEmbedExample").on("flippy:pageChange", (_, page) => {
  console.log("User navigated to page", page);
});

11. Monetization patterns

Flippy does not prescribe a payment provider but supports common patterns:

• Paywall gate: Hide the viewer until an authenticated flag returns true.
• CTA overlays: Inject custom buttons using flippy:ready and DOM overlays.
• Ad placements: Reserve regions around the viewer or add top/bottom banners inside the lightbox container.

12. Accessibility

• All interactive controls use buttons and links with focus styles inherited from Tailwind.
• Lightbox trap: focus returns to the trigger when closed.
• Drop zone includes role="button" and tabindex="0" for keyboard usage.
• Ensure alternative PDFs include selectable text for screen readers (avoid image-only scans when possible).

13. Performance tips

• Optimize PDFs (compress images, remove unused fonts).
• Preload frequently accessed PDFs via <link rel="preload">.
• Disable textLayer for image-only catalogs to reduce DOM load.
• Test on mid-range hardware to gauge GPU performance.

14. Troubleshooting

Slow performance

• Reduce page count in the PDF or split into multiple volumes.
• Disable shadows or reduce quality inside flippy.webgl.js if you customize the renderer.

15. Frequently asked questions

Can I load images instead of PDFs?

Yes. Provide an array of image URLs via the Flippy configuration (see flippy.js docs inside the source for images mode).

Does Flippy support mobile?

TouchSwipe powers gesture controls, and the layout is responsive. Always test on real devices to confirm performance.

How do I change icons?

Icons are loaded from /icons/unicon-*.css. Replace with your preferred icon font and update classes in the HTML or Flippy templates.

16. Support & next steps

If you extend the project:

• Create reusable components for repeated sections (Hero, Demos, Capabilities).
• Add automated tests around drop-zone validation if you integrate uploads server-side.
• Consider bundling with Vite or Next.js if you need advanced routing or data fetching.