Gallery Metadata Block

Dynamic Gutenberg block that publishes image galleries with per-instance custom metadata schema and client-side filter chips.

• Requires at least: WordPress 6.5
• Requires PHP: 8.1
• License: GPL-2.0-or-later
• Version: 1.1.0

Description

Gallery Metadata Block lets editors publish image galleries whose filter vocabulary (for example "Brand", "Material", "Star Rating") is defined per gallery and whose values are attached to individual images. All schema definitions and per-image values are stored inside the block's attributes — no custom post types, no post meta, no custom database tables.

Front-end visitors see one chip per schema value. Clicking a chip hides non-matching images in place via the Interactivity API and updates the URL using history.replaceState so a filtered view can be shared via link. Clicking a tile opens a centered modal that shows the image and its metadata side-by-side, with prev/next navigation and keyboard controls.

Designed to run unchanged on a standard WordPress install or on a WordPress VIP environment. No filesystem writes; no direct $wpdb queries; no custom REST endpoints.

Installation

1. Upload the plugin to wp-content/plugins/gallery-metadata-block.
2. Activate through the Plugins menu.
3. Insert the "Metadata Gallery" block from the Media category.

Frequently Asked Questions

Where is the metadata stored?

Inside the block's own attributes, serialised as JSON in post content. The plugin does not create custom post types, post meta, or custom tables.

Does the plugin emit structured data (schema.org)?

No. Structured-data output is delegated to the site's SEO plugin (Yoast, Rank Math). Editors who need schema.org markup for reviews, products, or similar should rely on the SEO plugin's native support.

What happens to filter URLs if neither Yoast nor Rank Math is active?

No canonical URL override is emitted. See AR-5 in Legal and Compliance below for the trade-off.

Does deactivating the plugin remove existing gallery blocks from posts?

The plugin does not alter post content on deactivation. Blocks remain in posts but render as raw HTML fallback until the plugin is reactivated. See AR-6.

Legal and Compliance

The following accepted risks are documented here so site administrators and editorial teams can evaluate exposure before adoption.

• AR-1 — Author-role schema edits. Authors (edit_posts) can insert galleries and modify per-gallery field schemas, including renaming fields that appear in published filter URLs. No capability split between schema-edit and value-entry.
• AR-2 — Silent image-slot removal. Removing an image slot from the gallery silently discards its per-image metadata with no confirmation.
• AR-3 — FOUC on shared filtered URLs. Visitors arriving via shared filtered URLs see a flash of all images before view.js hides non-matching tiles. No gmb-loading server-side suppression class; no content-visibility placeholder.
• AR-4 — No deprecated[] on day one. block.json ships with no deprecated[] array on day one. The first attribute-shape change will require editors to click "Attempt Recovery" per affected post unless the migration ships ahead of the breaking deploy.
• AR-5 — No SEO-plugin-fallback canonical. When neither Yoast nor Rank Math is active, filter-param URLs reach crawlers as fully indexable duplicates. No wp_head fallback canonical, no noindex meta.
• AR-6 — No deactivation admin warning. Plugin deactivation with posts still containing the gallery block emits no admin warning and no affected-post count.

Editorial-policy obligations (FTC/ASA affiliate disclosure, schema.org delegation to SEO plugins, GDPR revision retention, image attribution, field-name privacy review) are outside the plugin's technical surface and must be enforced by the operator.

Known Limitations

• Requires WordPress 6.5 or higher (the Interactivity API and apiVersion: 3 block support are hard requirements).
• Changing the block's attribute shape in a future release requires a deprecated[] entry with a migrate() function to avoid "Attempt Recovery" prompts on existing content (see AR-4).
• No canonical URL emission without an active SEO plugin (Yoast or Rank Math) — see AR-5.
• No admin-screen warning when deactivating the plugin while posts still contain the block — see AR-6.
• Structured data (schema.org for reviews, products, etc.) is delegated to the site's SEO plugin; this block does not emit its own JSON-LD.
• No FTC/ASA affiliate-disclosure hook. Editorial teams must ensure disclosures appear through other means.

Changelog

1.1.0

• UI: Clicking a tile now opens a centered modal (image + metadata side-by-side) instead of a sidebar panel.
• UI: Per-tile metadata list removed — metadata now appears in the modal only.
• UI: Grid fills the full available width.
• A11y: Modal has focus trap, Escape to close, and ← / → arrow navigation.

1.0.0

• Initial release.