Easy Mosaic WP Gallery

Easy Mosaic WP Gallery is a modern, accessible WordPress plugin for creating beautiful, lightweight image galleries — displayed in mosaic or grid layouts, complete with animation, pagination, and a fully accessible lightbox.

It’s built entirely with native WordPress APIs — CPTs, media modal, AJAX, and shortcodes — ensuring security, accessibility, and theme compatibility.

---

✨ Features

🧩 Gallery Management

• Registers a custom post type: Mosaic Galleries (emwg_album)
• Powerful admin UI with four configuration tabs:
  1. Main Panel – Manage images, edit Alt text inline, set Mosaic Weight (High / Medium / Low), copy shortcode.
  2. Album Options – Configure layout (Mosaic or Grid), grid columns, section width/background, animation, pagination, and lightbox preferences.
  3. Content Tab – Add album header, copy, CTA button, and customize content block placement.
  4. Gallery Images – Upload ZIP, download ZIP from URL, or select from the WP Media Library.

🖼️ Image Handling

• Upload ZIP archives or download from URL — images automatically unpacked and registered as attachments.
• Bulk add via native WP Media Modal.
• Inline editing:
  • Alt Text — auto-saves on blur (mirrors Media Library behavior).
  • Mosaic Weight — visually affects tile size in mosaic layout.
• AJAX-powered add, delete, and save.

⚙️ Layout & Display

• Mosaic or Grid layout modes.
• Grid mode supports configurable column counts.
• Adjustable container widths:
  • Fluid (100%)
  • Contained (1200px)
  • Narrow (800px)
• Optional custom container class for theme styling.
• Section background color and optional anchor ID for in-page navigation.
• Animations: OnLoad or OnScroll.
• Pagination options:
  • Limit visible images per page.
  • Choose Pagination Links or AJAX Load More.

💡 Lightbox

• Fully accessible lightbox with:
  • Keyboard navigation (← → Esc)
  • Swipe support on touch devices
  • Optional captions (from Alt text)
  • Optional navigation arrows
  • Focus trapping and role="dialog" with aria-modal="true"

🧱 Shortcode

Insert galleries anywhere with a shortcode:

[emwg_gallery id="123"]

Optional attributes override saved settings:

[emwg_gallery
    id="123"
    anchor_id="gallery-section"
    layout="grid"
    width="contained"
    grid_cols="4"
]

---

🪄 Installation

From the WordPress Admin

1. Upload easy-mosaic-wp-gallery.zip via Plugins → Add New → Upload Plugin.
2. Activate Easy Mosaic WP Gallery.
3. Open Mosaic Galleries → Add New.

From Source (Developers)

git clone https://github.com/yourusername/easy-mosaic-wp-gallery.git
cd easy-mosaic-wp-gallery
zip -r easy-mosaic-wp-gallery.zip .

Then upload easy-mosaic-wp-gallery.zip via the WordPress admin or copy the folder to wp-content/plugins/.

---

🧭 Usage

1. Go to Mosaic Galleries → Add New.
2. Add or import your images.
3. Configure layout, animation, pagination, and lightbox options.
4. Add optional header or content blocks.
5. Save the gallery and copy the shortcode shown on the Main Panel.
6. Paste the shortcode into any page, post, or block.

---

♿ Accessibility

• Semantic HTML and ARIA labeling for all interactive elements.
• Keyboard navigation and ESC close for the lightbox.
• Focus automatically moves to the close button when lightbox opens.
• Respects prefers-reduced-motion — simple fade replaces complex animation.
• Screen-reader text on all actionable controls.

---

🔒 Security

• Nonces and capability checks for all AJAX operations.
• Sanitization and escaping for all user inputs and database saves.
• File validation for all uploads and ZIP imports.
• Uses native WordPress functions:
  wp_handle_upload, download_url, unzip_file, and wp_insert_attachment.

---

🧰 Developer Notes

Key Classes | Class | Responsibility | |-------|----------------| | EMWG_CPT | Registers CPT and manages meta fields | | EMWG_Admin | Renders admin panels and metabox fields | | EMWG_Ajax | Handles AJAX CRUD, import, and pagination | | EMWG_Uploader | Imports ZIP and remote image archives | | EMWG_Shortcode | Renders gallery markup and front-end logic | | EMWG_Assets | Enqueues admin/front scripts and styles |

Assets

• assets/admin.js – Media modal integration, inline editing, ZIP import.
• assets/admin.css – Admin grid and field styles.
• assets/frontend.js – FLIP-style mosaic layout logic, AJAX pagination, lightbox controls.
• assets/frontend.css – Responsive CSS Grid and accessible lightbox UI.

Shortcode Example

echo do_shortcode('[emwg_gallery id="123" layout="mosaic" width="fluid"]');

---

🧪 Example Screenshots

View	Description
	Main Panel: Manage images inline (delete, alt text, weights)
	Album Options: Layout, pagination, and lightbox controls
	Content Tab: Add copy and CTA buttons with background color
	Frontend Mosaic: Responsive mosaic layout with lightbox

---

🧩 Roadmap

• [ ] Drag-and-drop image reordering in admin.
• [ ] Bulk alt-text editing with accessibility checks.
• [ ] Gutenberg block for visual embedding.
• [ ] Custom animation presets (fade, zoom, stagger).
• [ ] Image lazy-loading and progressive reveal.

---

🧑‍💻 Contributing

Pull requests are welcome! Please adhere to:

• WordPress PHP coding standards.
• Proper escaping (esc_html, esc_attr, etc.).
• Meaningful commit messages.

# Lint PHP
composer install
composer run lint

# Lint JS/CSS
npm run lint

---

📝 License

GPL v2.0 or later
Copyright © 2025
Built for developers who value accessibility, clean UI, and performance.

---