Taxonomy Gallery

Taxonomy Gallery

Taxonomy Gallery is a variation of the core Gallery block whose images are found when the page is viewed: the images of a chosen image taxonomy term, the latest images, or, on an image archive template, the images of the archive being viewed. It saves no images in the post and renders in any PhotoPress layout.

Requirements

• WordPress 6.6 or later, and the block editor.
• Image taxonomies to choose a term from: the Metadata tab's Image Taxonomies switch, or any taxonomy registered for attachments alone and public. With none, the gallery shows the latest images.
• The archive form needs a block theme: it is used in templates (the Image Archives template, an image taxonomy's own archive template, or a search template).

Using it

1. In the block inserter, choose Taxonomy Gallery.
2. Open the block's settings sidebar and set the Images panel.
3. Set the layout, slideshow and captions in the PhotoPress panel, as for any gallery (Gallery Layouts).

The inserter lists Taxonomy Gallery with the PhotoPress layouts.

The editor shows no images. It shows a placeholder with a sentence that says what the gallery will show, for example "12 images in Keywords: “Spring”, newest first, in the Masonry layout."

The placeholder in the canvas describes the gallery's query.

The Images panel: heading, details, taxonomy, term, number of images, order, links and size.

Where it finds images

The editor sets the source from where the block is. You do not choose it.

Where the block is	Source	Images shown
The taxonomy-attachment template (Image Archives), a taxonomy-<image taxonomy> or taxonomy-<image taxonomy>-<term> template, or the search or search-images template	archive	The images of the archive or search results page being viewed, with links to its other pages
Anywhere else (a post, a page, another template)	query	The images the Taxonomy, Term, Number of images and Order settings select

A gallery moved from one kind of template to the other changes source with it (sourceFor).

Images panel

Control	What it does	Default
Show heading	Shows a heading above the images when the gallery found some	Off
Heading	The heading's text. Shown while Show heading is on	Images
File name and title	Under each image, its file name and its title in place of its caption	Off
Taxonomy	The image taxonomy to take images from. Any (the latest images) takes them from every image. query source only	Any (the latest images)
Term	The term of that taxonomy. Type to search. None chosen: the latest images. query source only	None
Number of images	How many images to show, 1 to 100. query source only	12
Order	Newest first, Oldest first, By title or In random order. query source only	Newest first
Link to	Image page, Image file or None	Image page
Image size	Medium, Large or Full size	Large

The Taxonomy list offers taxonomies registered for images that visitors may see. A taxonomy for the admin only is not listed.

The inserter adds the gallery with the first layout turned on in the Gallery tab, Hide captions on, and wide alignment.

How it works

• The gallery renders as a core Gallery block saved with the images it found. PhotoPress layouts, the slideshow and Hide captions apply as they do to a gallery in a post. WordPress adds srcset and lazy loading to the images.
• A gallery that finds no images renders nothing, heading included.
• A term includes the terms under it in a hierarchical taxonomy.
• Taxonomy set but no Term chosen shows the latest images, as Any does.
• A term of a taxonomy that is not for images alone, or not public, shows nothing.
• With Link to set to Image page and the Pages & Search tab's Attachment pages off, the links go to the image files.
• With File name and title on, each image's caption is replaced by its file name and its title. The title links where the image links. Hide captions does not hide them.

Public images only

A Taxonomy Gallery shows only images WordPress counts as public: images not attached to a post, and images attached to a published post. An image attached to a draft, pending, private or scheduled post is left out (onlyPublicImages). Image taxonomy archives and image search results apply the same rule.

Random order

With Order set to In random order, PhotoPress keeps the IDs of up to 5,000 matching images, the most recently added, for ten minutes. Each time the gallery renders, it shuffles those IDs and shows the first Number of images of them (randomIds).

Paging on archives

With the archive source, the gallery shows the images of the main query's current page. The number per page is the main query's, set by Settings › Reading › Blog pages show at most. Below the gallery, a navigation element labeled "More images" links to the other pages, with Previous and Next links. It is shown when there is more than one page. On a single post or page, an archive gallery renders nothing.

A keyword's archive: a Taxonomy Gallery with the archive source.

WordPress integration

Hook	Type	Code	Purpose
pre_render_block	filter	ImageTemplates.php#L41	Renders a core/gallery with a photopressSource of archive, query or children in place of core (renderSourcedGallery)
register_block_type_args	filter	gallery.php#L72	Registers the photopress* attributes on core/gallery (addGalleryAttributes)
posts_where	filter	metadata.php#L137	Limits queries with the photopress_public_images query var to public images
pre_get_posts	action	metadata.php#L166	On an image taxonomy archive, makes the main query list public images (makeImagesVisibleToTaxQueries)

Rendering

renderSourcedGallery returns early when another pre_render_block filter already rendered the block. Otherwise it builds the images, writes core/gallery block markup with an image block for each (galleryMarkup), and renders it with do_blocks() and wp_filter_content_tags(). The gallery keeps its own attributes (layout, slideshow, alignment, columns, crop, anchor, class) less the query attributes in QUERY_ATTRIBUTES. The core render_block_core/gallery filters then run as for a saved gallery.

• query: queryArgs gives a WP_Query for attachment, status inherit, MIME type image, fields => ids, no_found_rows, with photopress_public_images set and a tax_query on term_id. It returns null for a taxonomy that fails ImageTaxonomies::isShownImageTaxonomy().
• archive: the image posts of the global $wp_query. Paging uses paginate_links() with the query's max_num_pages and the paged query var. The markup is <nav class="photopress-archive-images__pages">.
• Captions: imageItems uses wp_get_attachment_caption(), or, with photopressDetails, a figcaption.photopress-details with span.photopress-details__file and .photopress-details__title. The gallery figure then has the class photopress-has-details.
• The heading is <h2 class="wp-block-heading photopress-gallery-heading">.

Block attributes

Registered on core/gallery in PHP (gallery.php#L197) and in the editor (gallery-layouts.js#L40).

Attribute	Type	Default	Meaning
photopressSource	string	none	archive or query (children is the Child Pages Gallery)
photopressTaxonomy	string	none	Taxonomy name
photopressTerm	number	none	Term ID
photopressCount	number	12	Number of images, clamped to 1–100 on render
photopressOrder	string	date-desc	date-desc, date-asc, title or rand
photopressShowHeading	boolean	false	Show the heading
photopressHeading	string	unset: "Images"	Heading text
photopressDetails	boolean	false	File name and title under each image

The variation is registered in gallery-layouts.js#L157 as photopress-taxonomy-gallery. Its editor UI is TaxonomyGalleryEdit. The Term picker reads terms through the REST API. PhotoPress's image taxonomy routes answer only users with the edit_posts capability.

Data stored

Data	Where	Lifetime
photopress_gallery_ids_<md5 of the query>	Transient (set_transient())	10 minutes. Only for In random order. Deleted on uninstall

The block's settings are stored in the post's block markup.

Limits, quirks and known issues

• In random order picks from the 5,000 most recently added matching images only (highest attachment IDs).
• The file name shown is that of the attached file, which may be the -scaled copy WordPress makes of a large upload.
• On an archive of a taxonomy that is not for images, the main query lists posts. An archive gallery there shows only the images among them.

Related

• Gallery Layouts
• Child Pages Gallery
• Image Templates and Blocks
• Image Taxonomies
• Attachment and Taxonomy Pages
• Image Search
• Page Cache
• Gallery Images Added and Removed