MMM-PDFSlideshow

MMM-PDFSlideshow is a MagicMirror module that displays PDF documents as a slideshow. It utilizes PDF.js to dynamically render PDFs and supports two modes:

• Pageflip Mode: Displays one page at a time and automatically advances to the next. Once the last page is reached, it moves to the next PDF.
• Standard Mode: Renders the entire PDF in a scrollable container with the height fixed to the first page, ensuring only one page is visible at a time.

Features

• Dynamic PDF Listing: Fetches and displays all PDFs from a specified directory. Both local PDFs and downloaded remote PDFs are stored in the same folder.
• Remote PDF Handling: If a remote URL is provided (either via configuration or via an external notification), the module downloads that PDF into the designated folder and immediately jumps to it.
• External URL Notification: Send a GET_PDF_URL notification with a URL as its payload to download and display a remote PDF dynamically.
• Flexible Display: Can run in fullscreen mode or within a fixed-width container.
• Automatic Updates: Switches PDFs/pages based on a configurable display time.
• Responsive Scaling: Automatically scales PDFs to fit the display area.
• Transition Effects: Customizable transitions between PDFs for a smooth experience.
• Control Buttons: Optional on-screen control buttons (with Font‑Awesome icons) for navigating previous/next PDF and previous/next page.
• Direct Jump to Downloaded PDF: When a remote PDF is added (via config or notification), the module immediately jumps to it in the slideshow.

---

Installation

1. Clone the repository into your MagicMirror modules folder:

   cd ~/MagicMirror/modules
   git clone https://github.com/ChrisF1976/MMM-PDFSlideshow.git

2. No additional dependencies are required as PDF.js is loaded dynamically.
3. Add the module to your config.js:

   {
     module: "MMM-PDFSlideshow",
     position: "bottom_center", // Adjust as needed.
     config: {
       pdfContainer: "pdfs/",       // Folder containing local PDF files. The "/" is necessary. Also downloads are stored here.
       pdfPath: "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", //replace with your PDF-path or leave blank.
       displayTime: 10000,          // Time in milliseconds per PDF/page
       fullscreen: false,           // Enable or disable fullscreen mode. If true, set also `position` to a fulscreen region.
       width: "500px",              // Width when fullscreen is not disabled
       pageflip: true,             // Automatically flip through pages. Set to `true` for best navigation experience!
       transitionEffect: "fade",
       transitionEffectSpeed: 1000,
       pageflipTimeout: 10*1000,    // For manual navigation. After this interval the Slideshow restarts.
       buttonsVisible: true,        // Option to show/hide on-screen control buttons. 
     }
   }

4. Place PDF files in the specified directory (e.g., pdfs/).

---

Notifications

The module supports the following notifications:

Frontend (User/Module) Notifications

• PREVIOUS_PDF
  Action: Switches the slideshow to the previous PDF file in the list.
  Usage: Can be triggered via on-screen control buttons or sent as an external notification.

• NEXT_PDF
  Action: Switches the slideshow to the next PDF file in the list.
  Usage: Activated via control buttons or by sending this notification externally.

• PREVIOUS_PAGE
  Action: Moves to the previous page within the currently displayed PDF (only applicable when in pageflip mode).
  Usage: Can be invoked by a dedicated control button or by sending this notification.

• NEXT_PAGE
  Action: Advances to the next page within the current PDF (when pageflip mode is active).
  Usage: Triggered either by the control button or via an external notification.

• GET_PDF_URL
  Action: Downloads a remote PDF from the provided URL into the designated PDF folder. Once the download is successful, the module immediately jumps to that PDF in the slideshow.
  Usage: Send this notification with a valid URL string as its payload. This is useful for dynamically adding and displaying a remote PDF on demand.

Set pageflip: true, for best navigation experience!

---

How It Works

Frontend

• Dynamic PDF Listing:
  The module always requests the list of PDF files from the designated folder. Both local and downloaded PDFs become part of the slideshow.

• Remote PDF Handling:
  If a remote URL is provided via the pdfPath configuration or through a GET_PDF_URL notification, the module downloads that PDF into the same folder and immediately jumps to it.

• PDF Rendering:
  Loads PDF.js dynamically from a CDN and renders the PDF either in pageflip mode (displaying one page at a time) or in standard mode (rendering the full document in a scrollable container).

• Control Buttons:
  Optional on-screen control buttons are rendered (if enabled via configuration) for manual navigation through PDFs and pages. These controls pause the automatic slideshow for a configurable timeout.

Node Helper

• Folder Management:
  Reads the specified PDF directory (e.g., pdfs/) and filters only valid PDF files.

• PDF Downloading:
  Downloads remote PDFs (when triggered via pdfPath or GET_PDF_URL) into the same folder. If a PDF is already present, it is not downloaded again.

• Notification Handling:
  Sends the list of PDF files back to the frontend for display and notifies when a PDF has been downloaded. If a remote PDF is added and flagged for direct jump, the module will switch to it immediately.

• Error Handling:
  Logs errors if the folder cannot be read, if no PDFs are found, or if a download fails.

Limitations

• Fullscreen Mode Issue:
  In fullscreen mode, parts of the PDF might be cut off depending on your display setup.

• Initial Page Issue:
  Occasionally, on startup the first displayed page may not be page 1 of the PDF.

• Display Time:
  If only a single PDF or remote PDF is to be displayed, consider increasing displayTime to avoid flickering.

Customization

• Configuration Options:
  Adjust settings like displayTime, fullscreen, width, pageflip, transitionEffect, and buttonsVisible to fit your needs.

• Remote PDF Notifications:
  You can externally trigger a PDF download by sending a GET_PDF_URL notification with a valid URL string.

• Styling:
  Modify MMM-PDFSlideshow.css for further styling adjustments.

Troubleshooting

• PDF.js Not Loaded:
  Ensure you have an active internet connection.

• No PDFs Found:
  Verify the configured folder path and ensure that PDF files are present.

• Rendering Issues:
  Check for CSS conflicts with other modules or adjust the display settings.

• Remote PDF Issues:
  If the module doesn’t jump to a downloaded remote PDF, check the logs for errors in the download process.

License

This project is open-source and available under the MIT License.

Enjoy using MMM-PDFSlideshow to display your PDFs on MagicMirror!