Qaiyo Clean Gallery

Qaiyo Clean Gallery is a focused, dependency-free WordPress gallery plugin built for performance and clean markup. Each gallery is a Custom Post Type with its own settings, usable through a Gutenberg block or a shortcode. The frontend ships zero JavaScript dependencies — no jQuery, no Swiper, no PhotoSwipe — just a few kilobytes of plain modern JavaScript.

Unlike most gallery plugins, Qaiyo Clean Gallery is genuinely portable and self-hostable: you can move a whole gallery — with its images — from one site to another in a single ZIP file, it syncs live with your HappyFiles media folders, and it never phones home or loads your images through a third-party CDN.

What makes it different

• One-click ZIP export / import — move an entire gallery (settings, categories and the original image files) to another site in one downloadable ZIP. The source site does not have to stay online during import, and images transfer byte-for-byte. No database exports, no phpMyAdmin, no extra migration plugin.
• HappyFiles live-link — point a gallery at a HappyFiles media folder and it stays in sync automatically. Drop new images into the folder and they appear in the gallery — no re-import step.
• Import from Modula — bring your Modula galleries over without re-uploading a single image. You see what each gallery will become, and what will be different, before anything is created; Modula itself is left untouched.
• Duplicate image finder — scans your whole media library and groups byte-identical copies of the same picture, even when the filenames differ, so you can reclaim wasted disk space. It reports which galleries use each copy and never deletes anything by itself.
• No lock-in, no tracking — your images stay on your server and nothing is sent anywhere automatically. The only external interactions are the optional, click-only social share links and an optional WordPress.org directory query on an admin screen (see “External services” below).
• Truly multilingual — ships with 11 languages, each with correct plural rules.

Gallery layouts

• Grid — classic fixed-ratio column grid
• Masonry — Pinterest-style variable-height columns
• Standard — uniform 1:1 squares for portfolios and shops
• Justified — equal-height rows with varying widths (Flickr style)
• Bento — asymmetric multi-sized grid with hero cells
• Showcase — threes: one large image beside two stacked ones, mirrored every other group
• Mosaic — tiles of mixed sizes packed edge to edge with no gaps; the arrangement is worked out on the server, so it is the same on every visit and nothing jumps while the page loads

You pick one from a row of mock-ups above the images, not from a dropdown — each card draws what the layout actually does, and only the settings that layout uses are shown underneath it.

Not sure which one fits? The Suggest a layout button in the gallery editor analyses the aspect ratios of your images — how many are portrait, landscape or square, and how much they vary — and recommends the layout that suits them best, with a one-line explanation. It works before the gallery is even saved.

Lightbox

• Keyboard navigation (arrow keys / Esc) and touch-swipe friendly
• Image counter, captions and a responsive mobile layout
• Deep linking — opening an image updates the URL (#qcg={id}&img={index}) so an exact image can be linked, bookmarked and shared
• Social share buttons inside the lightbox — Facebook, X, Pinterest and copy-link
• Right-click protection — optional casual-download protection (disables right-click and image drag)

All-galleries view

The [qaiyo_clean_gallery_all] view lists every gallery as a paged card grid with:

• Category filter buttons
• Sorting by date (newest / oldest) or title (A→Z / Z→A)
• Load-more pagination
• A 3 / 4 column switcher whose icon colors you can customize
• Open in place — add open="lightbox" and a click on a card opens that gallery’s photos in the lightbox right there, instead of leaving for the gallery page. The photos are fetched only when a card is opened, so a listing of many large galleries stays light. A gallery the visitor may not see (password protected, for instance) still leads to its own page, where the password form is.

Import from Modula

If the site has Modula galleries, Clean Gallery → Export / Import shows an Import from Modula card. It works even after Modula has been deactivated.

• Nothing is uploaded again. The new galleries point at the same images in your Media Library.
• You see the plan first. Each Modula gallery is listed with the layout it will get and a plain list of what will be different — a column count outside the supported range, per-image links, filters, a gallery type with no counterpart. Nothing is dropped silently.
• Modula is not touched. Its galleries, settings and albums stay exactly as they are, so you can compare the two side by side.
• Safe to run again. A gallery that is already imported is skipped, not duplicated.
• Layouts carry over. Modula’s Creative type becomes a Mosaic; a Custom grid keeps the size you gave each image; Masonry and Justified map to their namesakes.
• Albums become categories. Each imported gallery is filed under the album it belonged to. An album that opened its galleries in a lightbox keeps doing so: its embed is swapped for a listing with open="lightbox".
• Everything can be undone. If a gallery did not come over the way you wanted, undo its import: the gallery goes to the trash (recoverable), and wherever a Modula embed was swapped for it, the original is put back — exactly as it was, without losing anything else you changed on the page since. A gallery that is still shown somewhere is never removed from under that page; you are told where it is used instead.
• Embeds can be swapped for you. Pages that show a Modula gallery through a shortcode or a block are listed, and the embed can be replaced with its counterpart. The page as it was is saved as a revision first, and a page is left alone if that cannot be done. Pages built with a page builder are listed too, but never edited — swap those in the builder.

Overview dashboard

A dedicated landing page under Clean Gallery → Overview shows at-a-glance stats — number of galleries, published, drafts, total images, views, categories and HappyFiles status — plus quick actions for creating a gallery, finding duplicates, exporting/importing and opening help.

Placeholder images

Waiting for the client’s photos? Turn on Placeholder images in the gallery editor, pick a number and an orientation mix, and the gallery renders neutral sample tiles with realistic proportions in whatever layout you chose — Masonry, Justified and Showcase behave exactly as they will with the real pictures. Placeholders are bundled with the plugin, never added to the Media Library, not counted as views, and disappear automatically as soon as a real image is added.

Gallery views

A private view counter shows which galleries people actually look at — in the gallery list (sortable), in the editor sidebar and as a total on the Overview page. A view is counted once per visitor session, when the gallery comes into view. It stores one number per gallery on your own site: no cookies, no IP addresses, no external service. Logged-in editors and known bots are not counted, and the counter can be switched off under Info & Help.

Qaiyo Dashboard card

If you run Qaiyo Admin Booster, its WordPress Dashboard widget collects a small summary card from every active Qaiyo plugin. Clean Gallery’s card shows your galleries, images and your most viewed (or largest) gallery. With Qaiyo Social Video Embed active too, the two merge into one Media statistics card that also counts the video embeds in your published content. No data leaves your site.

Duplicate image finder

Clean Gallery → Duplicates scans your media library and finds pictures that are byte-for-byte identical, even if they were uploaded under different names (photo.jpg, photo-1.jpg, photo-scaled.jpg). Every image is fingerprinted with a content hash — the same technique the gallery importer uses to avoid re-uploading files it already has.

• The scan runs in batches, so even a large media library never hits a PHP time limit
• Results are grouped per duplicate set, showing the total number of redundant files and the disk space they waste
• Each copy lists the galleries that use it, and links straight to the Media Library entry
• Nothing is deleted automatically — you stay in control of what gets removed

Performance & SEO

• Zero JavaScript dependencies on the frontend
• Native browser lazy loading (loading="lazy")
• Automatic image compression on upload — images over ~1.5 MB are compressed to under ~1 MB using Imagick or GD
• schema.org structured data: ImageGallery, ImageObject and ItemList
• ARIA labels and full keyboard navigation

Editor & embedding

• Each gallery is a Custom Post Type with a drag-and-drop image manager
• A copy-ready shortcode box on the editor screen
• A native Qaiyo Clean Gallery Gutenberg block (server-side rendered)
• Theme-overridable single-gallery template

Shortcodes:

• [qaiyo_clean_gallery id="42"] — a single gallery. Optional attributes: layout, columns, lightbox, captions, lazy, gap, row_height, and ids="101,102" to render attachments directly without a gallery post.
• [qaiyo_clean_gallery_all] — all galleries as a paged card grid. Attributes: card_columns, gallery_columns, filter, orderby, order, per_page, category, and open="lightbox" to open a gallery’s photos in place instead of on its own page.

Internationalization

Bundled translations: English, Hungarian, German, French, Spanish, Italian, Portuguese, Russian, Japanese, Turkish and Polish. Locale variants (for example de_CH, fr_BE, es_MX, pt_BR) automatically fall back to their base language.

For developers

Everything is namespaced under the qaiyo_clean_gallery prefix, with filters for customization:

• qaiyo_clean_gallery_layouts — register your own layout (see HOOKS.md)
• qaiyo_clean_gallery_justified_row_height — target row height for the Justified layout
• qaiyo_clean_gallery_happyfiles_taxonomy, qaiyo_clean_gallery_hf_orderby, qaiyo_clean_gallery_hf_order — HappyFiles folder source and ordering
• qaiyo_clean_gallery_compress_threshold, qaiyo_clean_gallery_compress_max_bytes, qaiyo_clean_gallery_compress_quality_step, qaiyo_clean_gallery_compress_quality_floor — image compression tuning
• qaiyo_clean_gallery_cpt_slug, qaiyo_clean_gallery_tax_slug — the single-gallery and category URL slugs

Part of the Qaiyo family

Qaiyo Clean Gallery is part of the Qaiyo plugin family — https://qaiyo-plugins.com — support: [email protected]

External services

This plugin does not send any data anywhere on its own and does not use any tracking. It interacts with the following external services, in the ways described below.

Facebook, X and Pinterest share links (optional)

When the Social share buttons setting is enabled (Clean Gallery → Info & Help), the lightbox shows share links for Facebook, X and Pinterest. No connection to these services is made while browsing — a request happens only when a visitor clicks one of the share links, which opens that provider’s standard share page in a new browser tab.

What is sent on click, as URL parameters of the opened share page: the URL of the page containing the gallery (all three services), and for Pinterest additionally the URL of the shared image and its caption/title, so the provider can pre-fill the share dialog. The plugin itself transmits nothing; the visitor’s browser opens the provider’s page, where the provider’s own terms apply:

• Facebook (Meta Platforms, Inc.) — Terms of Service, Privacy Policy
• X (X Corp.) — Terms of Service, Privacy Policy
• Pinterest (Pinterest, Inc.) — Terms of Service, Privacy Policy

The copy-link button only copies the URL to the visitor’s clipboard locally; it contacts no service. If the Social share buttons setting is disabled, none of these links are rendered.

WordPress.org plugin directory (admin only)

The admin-only Discover Qaiyo screen queries the official WordPress.org plugin directory API (api.wordpress.org) to list our other free plugins. The request is made only when an administrator opens that screen, contains only the plugin-author query (no personal data), and its result is cached for 12 hours. This is the same WordPress.org infrastructure the built-in “Add Plugins” screen uses. See the WordPress.org privacy policy. No request is made on the frontend of your site.