MW Quick PDF Viewer

Developed by Mertsch-Web

Version: 1.0.2
Release Date: January 8, 2026
Compatibility: Joomla 5.0 - 6.999
PHP Version: 8.1+

---

Key Features

? Easy to Use

• One-Line Integration: Simply add {gallery path='pdfs/folder'} to your article
• No Coding Required: Perfect for editors without technical knowledge
• Automatic Detection: Scans folders and lists all PDF files automatically
• Flexible Syntax: Use {gallery} or {pdflist} - both work

? PDF Management

• Smart File Detection: Automatically scans folders for PDF documents
• File Information: Displays filename and size for each document
• Sorting: Alphabetical sorting of files
• Folder Structure: Supports subfolders and complex directory structures
• No Database: Works directly with your file system

?? Professional Modal Viewer

• Embedded Display: PDFs are displayed directly in the browser (iframe-based)
• Native Browser Viewer: Uses your browser's built-in PDF features
• Fullscreen Mode: Maximum readability for your documents
• Smooth Animations: Elegant fade-in and fade-out effects
• Loading Feedback: Spinner animation during loading

? Customizable Design

• Three Button Styles:
  • Default: Classic white button with gray border and red hover
  • Minimal: Subtle transparent style with fine border
  • Solid: Eye-catching red button with white text
• Responsive Grid: 1-4 column layout, fully customizable
• PDF Icons: Optional toggle-able PDF symbols on buttons
• Modern UI: Clean, professional design for 2026
• Hover Effects: Visual feedback on mouse hover
• Dark-Mode-Ready: Optimized for light and dark themes

? Mobile Optimization

• Touch-Friendly: Optimized for touchscreen operation
• Responsive Breakpoints: Automatically adapts to screen sizes
• Mobile-First Approach: Developed with priority on mobile devices
• Swipe Gestures: Intuitive operation on smartphones and tablets

? Functionality

• Download Function: Direct download button for each PDF
• Print Function: Instant printing from the viewer
• Keyboard Navigation: ESC key to close the modal
• Multilingual: Fully translated (German & English)
• Accessibility: Screen reader friendly and barrier-free

? Technical Highlights

• No Dependencies: No jQuery or external frameworks required
• Vanilla JavaScript: Fast and lightweight
• CSS Grid Layout: Modern layout technology
• Clean Code: PSR-12 compatible, well documented
• Performance: Optimized for fast loading times
• Security: HTML escaping and input validation

---

Installation

Prerequisites

• Joomla 5.0 or higher (up to Joomla 6.999)
• PHP 8.1 or higher
• PDF files in an accessible folder

Installation Steps

1. Download: Download the latest version as a ZIP file
2. Joomla Backend: Navigate to System ? Extensions ? Install
3. Upload: Upload the ZIP file (Drag & Drop or Browse)
4. Activation: Go to System ? Plugins ? Filter: Content
5. Find Plugin: Search for "MW Quick PDF Viewer"
6. Activate: Click on the status to activate the plugin
7. Done: The plugin is now ready to use!

---

Usage

Quick Start

Insert the following shortcode in any Joomla article or module:

{pdflist path='pdfs/my-folder'}

or alternatively:

{pdflist path='pdfs/my-folder'}

Important: The path is relative to the Joomla root directory.

Parameter Reference

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| path | String | Yes | - | Relative path to PDF folder from Joomla root |
| columns | Integer | No | 2 | Number of columns (1-4), overrides plugin setting |
| title | String | No | - | Heading above the PDF list |

Usage Examples

Simplest Variant:
{pdflist path='pdfs/manuals'}
? Displays all PDFs from "pdfs/manuals" folder in 2 columns (default)

With Column Count:
{pdflist path='pdfs/forms' columns='3'}
? Displays PDFs in 3 columns

With Title:
{pdflist path='pdfs/reports' title='Annual Reports 2025'}
? Displays a heading above the PDF list

All Parameters:
{pdflist path='pdfs/documents/important' columns='4' title='Important Downloads'}
? Complete configuration with all options

Subfolders:
{pdflist path='pdfs/departments/marketing/2025'}
? Supports arbitrarily deep folder structures

---

Plugin Configuration

Open the plugin settings under System ? Plugins ? MW Quick PDF Viewer

Basic Settings

Number of Columns (Default: 2)
- Determines the number of button columns in the grid layout
- Options: 1, 2, 3, or 4 columns
- Can be individually overridden per shortcode
- Responsive: Automatically fewer columns on mobile devices

Button Style (Default: Default)
- Default: White background, gray border, red hover effect
- Minimal: Transparent background, subtle border, minimalist
- Solid: Red background, white text, eye-catching and modern

Show Icons (Default: Yes)
- Shows PDF icon on each button
- SVG-based icon for sharp display
- Can be disabled for minimalist design

Support Section

The plugin includes an integrated support section with:
- Information about the developer
- Direct contact options
- PayPal donation button to support development

---

Modal Viewer in Detail

Opening the Viewer

• Click on any PDF button
• Modal appears with smooth fade-in animation
• Background is dimmed (overlay)
• Main content remains visible in background (blurred)

Viewer Functions

PDF Display
- Uses native browser PDF viewer (iframe)
- Full browser features available
- Zoom, scroll, text search possible
- Automatic size adjustment

Action Buttons

1. Download Button (?)

   • Downloads the PDF file
   • Uses the original filename
   • Compatible with all browsers
   • HTML5 download attribute

2. Print Button (?)

   • Opens browser print dialog
   • Directly from the viewer
   • Uses native window.print()
   • Optimized for PDF printing

3. Close Button (×)

   • Closes the modal
   • Alternative: Press ESC key
   • Alternative: Click on background
   • Smooth fade-out animation

Loading Status

• Spinner animation during loading
• Visual feedback for the user
• Disappears automatically after loading

Keyboard Shortcuts

• ESC: Close modal
• Additional browser shortcuts active in PDF viewer

---

Design System

Color Palette

Default Theme:
- Primary Color: #dc2626 (Red)
- Hover: #ef4444 (Light Red)
- Text: #1f2937 (Dark Gray)
- Border: #d1d5db (Light Gray)
- Background: #ffffff (White)
- Overlay: rgba(0, 0, 0, 0.5) (Semi-transparent Black)

Typography

• System font stack for optimal readability
• Sans-serif fonts: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto
• Responsive font sizes
• Optimal line heights for readability

Spacing & Grid

• CSS Grid with gap for consistent spacing
• Responsive breakpoints for all screen sizes
• Padding and margins in 8px grid
• Maximum container width for optimal readability

Animations

• Smooth transitions (0.2s - 0.3s)
• Fade-in/fade-out effects
• Hover animations for interactive elements
• Loading spinner with CSS animation

JavaScript API

```javascript
// Open modal
function openMWPDFModal(id, url, filename)

// Close modal
function closeMWPDFModal(id)

// Download PDF
function downloadMWPDF(url, filename)

// Print PDF
function printMWPDF(id)
```

Styling Classes

css .mw-pdf-grid /* Grid container */ .mw-pdf-button /* Base button */ .mw-pdf-button-default /* Default style */ .mw-pdf-button-minimal /* Minimal style */ .mw-pdf-button-solid /* Solid style */ .mw-pdf-modal /* Modal overlay */ .mw-pdf-modal-content /* Modal content */

Performance

• File Operations: Cached in PHP variables
• CSS: Inline, minified
• JavaScript: Inline, Vanilla JS
• No External Requests: Everything local
• Lazy Loading: iframes load PDFs on-demand

Security

• Input Validation: All paths are validated
• Directory Traversal Protection: realpath() check
• XSS Protection: HTML escaping for all outputs
• File Type Check: Only PDF files are accepted
• Permissions: Check for readable files

---

Browser Compatibility

| Browser | Version | PDF Display | Download | Print |
|---------|---------|-------------|----------|-------|
| Chrome | 90+ | ? Yes | ? Yes | ? Yes |
| Firefox | 88+ | ? Yes | ? Yes | ? Yes |
| Safari | 14+ | ? Yes | ? Yes | ? Yes |
| Edge | 90+ | ? Yes | ? Yes | ? Yes |
| Opera | 76+ | ? Yes | ? Yes | ? Yes |
| Mobile Safari | iOS 14+ | ? Yes | ? Yes | ?? Limited |
| Chrome Mobile | Android 11+ | ? Yes | ? Yes | ? Yes |

Notes:
- Older browsers might not display PDFs inline (download instead of display)
- Mobile browsers have partially restricted printing functions
- PDF.js fallback can be integrated if needed

---

Frequently Asked Questions (FAQ)

General Questions

Q: Does the plugin work with Joomla 4?
A: No, MW Quick PDF Viewer was specifically developed for Joomla 5 and 6. A separate version would need to be created for Joomla 4.

Q: Can I display other file types?
A: No, the plugin is exclusively optimized for PDF documents. Other file types are ignored.

Q: How many PDFs can I have in a folder?
A: Theoretically unlimited, but for performance reasons we recommend a maximum of 50-100 PDFs per folder.

Q: Are subfolders supported?
A: Yes, you can specify arbitrarily deep folder structures (e.g., pdfs/year/month/category).

Technical Questions

Q: Do I need to install jQuery?
A: No, the plugin uses Vanilla JavaScript and has no dependencies.

Q: Are PDFs uploaded to a database?
A: No, the plugin works directly with your file system. Simply place PDFs in a folder and you're done!

Q: Can I customize the design?
A: Yes, you can include your own CSS rules in your template to override the appearance.

Q: Does it work with all PDF files?
A: Yes, as long as the browser can display PDFs. With very large files (>50MB), loading times may occur.

Troubleshooting

Q: PDFs are not displayed
A: Check:
- Is the plugin activated?
- Does the specified path exist?
- Are the file permissions correct (readable)?
- Does the folder actually contain PDF files?

Q: The path doesn't work
A: The path must be relative to the Joomla root directory. Example: If your PDFs are located at www.yoursite.com/documents/pdfs/, use path='documents/pdfs'.

Q: Modal doesn't open
A: Check the browser console for JavaScript errors. There may be conflicts with other extensions.

Q: Download doesn't work
A: Make sure the browser allows pop-ups and downloads from your domain.

---

Changelog

Version 1.0.2 (January 8, 2026)

• ? Stable release version
• ? Extended documentation (German & English)
• ? Update server configured and tested
• ? Minor bugfixes

Wishes and suggestions are welcome! Contact us at info@mertsch-web.de

---

Support & Community

Official Channels

Website
https://mertsch-web.de

Email Support
info@mertsch-web.de

Documentation
This README.md file (constantly updated)

Update Server
https://mertsch-web.de/updates/mwquickpdf.xml

Support Requests

When submitting support requests, please provide the following information:
- Joomla version
- PHP version
- Plugin version
- Error message (if any)
- Browser and version
- Steps to reproduce the problem

Bug Reports

If you have found a bug:
1. Check if the bug still exists in the latest version
2. Search in known issues (if available)
3. Contact us with a detailed description
4. Include screenshots or error messages

Feature Requests

Have an idea for a new feature?
- Describe the use case
- Explain what problem should be solved
- Send us your idea via email

---

Donations & Support

MW Quick PDF Viewer is a free open-source plugin that has been developed with a lot of love and time. If you would like to support the development, we would be very happy about a small donation!

Why donate?
- ? Coffee for long development nights
- ? Server and hosting costs
- ? Further education and new technologies
- ? Development of new features
- ? Bugfixes and support
- ? Improved documentation

Donate via PayPal:

Every amount helps and is greatly appreciated! Thank you for your support! ??

---

About the Developer

Mertsch-Web is a web development studio focusing on Joomla extensions and custom web solutions.

Expertise:
- Joomla Plugin & Module Development
- Custom Joomla Templates
- PHP Backend Development
- Frontend Development (HTML, CSS, JavaScript)
- Responsive Web Design
- Performance Optimization

Other Projects:
- MW Quick Gallery (predecessor of this plugin)
- More Joomla extensions in planning

Contact:
- ? Website: https://mertsch-web.de
- ? Email: info@mertsch-web.de
- ? Location: Germany

---

License & Copyright

```
MW Quick PDF Viewer - Joomla Plugin
Copyright (C) 2025-2026 Mertsch-Web

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see .
```

GNU General Public License v2.0 or higher

This means:
- ? Free use (private & commercial)
- ? Modifications to the code allowed
- ? Distribution allowed
- ? Source code available
- ?? Changes must be documented
- ?? Same license when redistributing
- ?? No warranty or liability

---

Credits & Acknowledgments

Developed with:
- PHP 8.1+
- Joomla 5/6 Framework
- Vanilla JavaScript (ES6+)
- CSS Grid & Flexbox
- SVG Icons
- Lots of coffee ?

Special thanks to:
- The Joomla community for feedback and support
- All beta testers of the first versions
- Users who reported bugs
- All donors who support the development

Inspired by:
- Modern PDF viewer solutions
- Material Design Principles
- Best practices in UX/UI design

---

Important Notes

Disclaimer

The plugin is provided "as is" without any warranty. The developer assumes no liability for:
- Data loss
- Server problems
- Conflicts with other extensions
- Security vulnerabilities due to misconfiguration
- Indirect or direct damages

Security Notes

• Make sure PDF folders don't contain sensitive data
• Set appropriate file permissions
• Check regularly for updates
• Use HTTPS for your website
• Implement access restrictions if necessary

Best Practices

1. Folder Structure: Organize PDFs in logical folders
2. Filenames: Use descriptive names without special characters
3. File Size: Optimize PDFs before upload (recommended < 5MB)
4. Updates: Keep the plugin up to date
5. Backups: Regularly backup your Joomla installation
6. Testing: Test the plugin after Joomla updates

---

Thank you for using MW Quick PDF Viewer! ?

If you have any questions or problems, we are happy to help.