Skip to content

Image Templates and Blocks

Jump to bottom
padams edited this page Oct 14, 2026 · 4 revisions

Image Templates and Blocks

PhotoPress gives block themes two templates: Image Archives, for the archive pages of image taxonomy terms, and Image Pages, for an image's own page. They are built from the Taxonomy Gallery, the Attachment Image block and the Image Metadata block, which you can also place in your own templates.

Requirements

  • Templates: WordPress 6.7 or later (register_block_template()) and a block theme. On WordPress 6.6 the blocks work and the templates are not registered.
  • The templates use the theme's header and footer template parts.
  • Image Archives: image taxonomies, from the Metadata tab's Image Taxonomies switch or any taxonomy registered for attachments alone.

Settings

Open PhotoPress › Settings › Pages & Search. Each template is offered while its kind of page is on (Attachment and Taxonomy Pages).

Control What it does Default
Attachment pages Gives each image a page of its own. While on, the Image Pages template is offered. Off, an image's page address and links to it go to the image file WordPress's own Attachment pages setting until saved: off on sites installed since WordPress 6.4, on for older sites
Image taxonomy pages Gives each term of an image taxonomy an archive page of its images. While on, the Image Archives template is offered. Off, the terms are kept and shown without links On

The Attachment pages switch
Attachment pages, in the Pages & Search tab.

The Image taxonomy pages switch
Image taxonomy pages, in the Pages & Search tab.

Templates

Image Archives (taxonomy-attachment)

The archive page of a term of an image taxonomy, such as a keyword or a camera. It holds:

  1. The header template part.
  2. Query Title, as the archive's title.
  3. Term Description.
  4. A Taxonomy Gallery with the archive source: the archive's images, in the Masonry layout, linked to their image pages, at the Large size, wide, with captions hidden. Links to the archive's other pages follow it.
  5. The footer template part.

The Image Archives template on the front end
A keyword's archive with the Image Archives template.

Image Pages (attachment)

An image's own page. It holds:

  1. The header template part.
  2. Attachment Image, wide.
  3. Title, as a level 1 heading.
  4. Content: the image's description.
  5. Image Metadata with every public taxonomy registered for attachments, terms linked.
  6. Image Metadata with the exposure details: camera model, aperture, shutter speed, ISO, focal length and date taken, unlinked.
  7. The footer template part.

The Image Pages template on the front end
An image's page with the Image Pages template.

Editing them

Open Appearance › Editor › Templates. The templates are listed as Image Archives and Image Pages, described as "From PhotoPress."

The PhotoPress templates in the Site Editor
Image Archives and Image Pages in the Site Editor's template list.

PhotoPress writes nothing to the theme or the database. Editing a template in the Site Editor saves the edited copy for the theme. Reset in the Site Editor brings back PhotoPress's version.

When the theme's own template is used

The theme's template wins when it has one of the same name or a more specific one.

Page Templates WordPress looks for, most specific first PhotoPress's
Image taxonomy archive taxonomy-<taxonomy>-<term>, taxonomy-<taxonomy>, taxonomy-attachment, taxonomy, archive, index taxonomy-attachment
Image page <type>-<subtype> (for example image-jpeg), <subtype> (jpeg), <type> (image), attachment, single-attachment-<slug>, single-attachment, single, singular, index attachment

WordPress has no taxonomy-attachment step. PhotoPress adds it before taxonomy for archives of taxonomies registered for attachments alone, unless the list has it already, as themes built on the Frame framework (Ansel, Dorthea) do (withTaxonomyAttachment). This also applies to classic themes: a taxonomy-attachment.php file in the theme is used for those archives.

A theme's taxonomy.html, archive.html, single.html or singular.html does not replace PhotoPress's templates. A theme's image.html replaces Image Pages.

Blocks

Attachment Image

The image of an image (attachment) page, at the size you choose, with its caption. Use it in the Image Pages template or your own attachment template.

Control What it does Default
Image size Medium, Large or Full size Large
Link to the image file Links the image to its file Off
Caption Shows the image's caption under it On

The block supports wide and full alignment, margin and padding. In a template the editor shows a placeholder. On the site it renders the image with srcset. On a page that is not an image's, it renders nothing.

On an image page, WordPress puts the image before the description in the post content. The Attachment Image block removes that copy, so the image is not shown twice.

Image Metadata

The metadata of the current image: its taxonomy terms, such as keywords, people and places, and the exposure details from its file. The block was named Image Taxonomies before. Its block name is still photopress/image-taxonomies.

The Rows panel
The Rows panel.

Rows panel. A checklist of the taxonomies visitors may see, then the exposure details: Camera model, Aperture, Shutter speed, ISO, Focal length and Date taken. Check the rows to show. Use Move up and Move down to order the checked rows. With none checked, the block shows every public taxonomy registered for attachments, in registration order, and no exposure details. A row saved for a taxonomy no longer registered or public stays listed under its name so you can uncheck it.

Display panel.

The Display panel
The Display panel.

Control What it does Default
Link terms Links each term to its archive page of images On
Show labels Shows each row's name before its terms or value On

The block also supports wide and full alignment, margin, padding, font size, line height, and text, background and link colors.

What it shows:

  • One row per checked taxonomy that has terms for the image: the taxonomy's name, then its terms separated by commas.
  • One row per exposure detail the file gave. A value that is empty or zero is skipped.
  • Terms link only while the taxonomy has archive pages. With Image taxonomy pages off, they show unlinked.
  • A taxonomy for the admin only is never shown.
  • With no rows to show, the block renders nothing.
Detail Shown as
Aperture f/2.8, f/8
Shutter speed 1/250 s for a fraction of a second, otherwise seconds, such as 2 s
Focal length 50 mm
ISO 400
Date taken The site's date format (Settings › General). The camera's clock time is shown as recorded, without a time zone shift
Camera model As in the file

In the editor, the block previews the current image's rows from the server. In a template it shows a placeholder.

The Image Metadata block on an image page
Image Metadata rows on an image page.

Search Summary and Search Posts

Two blocks for search results pages, used by the Image Search template. Search Summary shows a label, the search terms as the page's title, and the number of images found (of results, on a search without images). Search Posts shows a few of the posts and pages a search with images found, with a link to all of them, and a note when nothing was found. See Image Search.

Legacy widgets

The Display Taxonomies and Display Image Exif widgets are kept so that sites that placed them before keep working. New sites should use the Image Metadata block. The widgets need a classic theme with a widget area.

Widget Setting Shows
Display Taxonomies (PhotoPress) Image Taxonomies: taxonomy names, separated by commas. Default photos_keywords, photos_camera, photos_lens, photos_city, photos_state, photos_country, photos_people The image's terms, linked, with labels
Display Image Exif (PhotoPress) Details, separated by commas: camera, aperture, shutter_speed, iso, focal_length, created_timestamp. Default iso,aperture,camera The image's exposure details, unlinked, with labels

Both have a Title: setting and render the same markup as the Image Metadata block. Both work on image (attachment) pages.

In the widgets block editor neither widget is offered. Widgets already placed still show on the site. To replace one, select it and use the block toolbar's transform menu to turn it into Image Metadata:

  • The block gets the widget's taxonomies or details, in the same order.
  • Display Taxonomies becomes a block with Link terms and Show labels on. Display Image Exif becomes a block with Link terms off and Show labels on.
  • The widget's title becomes a Heading block, level 2, above it.

With the Metadata tab's Image Taxonomies switch on, PhotoPress also registers a widget area named Image Page. PhotoPress does not display it. A classic theme shows it only where the theme calls it.

WordPress integration

Hook Type Code Purpose
taxonomy_template_hierarchy filter ImageTemplates.php#L46 Adds taxonomy-attachment before taxonomy on archives of attachment-only taxonomies (addTaxonomyAttachment)
the_content filter (removed) ImageTemplates.php#L489 The Attachment Image block removes prepend_attachment() from it
widgets_init action metadata.php#L134 Registers both widgets with register_widget() (registerWidgets)
widget_types_to_hide_from_legacy_widget_block filter metadata.php#L929 Hides xmpdisplaywidget and exifdisplaywidget from the Legacy Widget block
widget_title filter (applied) XmpDisplayWidget.php#L54, ExifDisplayWidget.php#L63 Core's filter, applied to each widget's title
search_template_hierarchy filter ImageSearch.php#L60 Image Search template. See Image Search.

Templates

Blocks

Block Name Registered Rendered by
Attachment Image photopress/attachment-image block.json, ImageTemplates.php#L42 renderAttachmentImage
Image Metadata photopress/image-taxonomies block.json, metadata.php#L142 ImageTaxonomies::renderBlock
Search Summary photopress/search-summary block.json, ImageSearch.php#L66 renderSummary
Search Posts photopress/search-posts block.json, ImageSearch.php#L63 renderPosts

All four are dynamic blocks registered with register_block_type() from block.json, and save only their attributes.

  • Attachment Image and Image Metadata take the post from the postId block context, and fall back to the queried object or get_the_ID(). Attachment Image uses wp_get_attachment_image() and get_block_wrapper_attributes().
  • Image Metadata attributes: taxonomies (array of taxonomy names and exif:<key> rows), linkTerms (default true), showLabels (default true).
  • renderRows reads terms with get_the_terms(), links them with get_term_link() when is_taxonomy_viewable(), and reads exposure details from image_meta in wp_get_attachment_metadata(). Formatting is in formatExif.
  • Markup: div.display-taxonomy-terms-widget holding one div.container per row, each with div.label and div.terms. The Exif widget adds the class display-exif-widget.
  • The editor's taxonomy list comes from /wp/v2/taxonomies?type=attachment, filtered by the photopress_public REST field PhotoPress adds to each taxonomy (ImageTaxonomyRest.php#L80). The preview uses the core block renderer route.
  • Widget transforms: fromWidget and fromExifWidget, from core/legacy-widget. The widgets register with show_instance_in_rest so the widgets editor has their settings.

Data stored

None of their own. Edited templates are stored by WordPress as wp_template posts. Widget settings are stored by WordPress in widget_xmpdisplaywidget and widget_exifdisplaywidget.

Limits, quirks and known issues

  • The Attachment Image block's removal of prepend_attachment lasts for the rest of the request.
  • Display Taxonomies (PhotoPress) prints its widget wrapper and title even when the image has no terms. Display Image Exif (PhotoPress) prints nothing when there are no details.
  • Image Metadata shows exposure details only for images. On a post it shows that post's terms in the chosen taxonomies, if any.
  • With no rows checked, Image Metadata shows every public taxonomy registered for attachments, including one shared with other post types.

Related

Home

Galleries

Metadata

Pages and search

Media

Operation

Clone this wiki locally