Repository navigation
Child Pages Gallery
Child Pages Gallery is a variation of the core Gallery block that shows the published pages under the page it is on. Each page appears as its featured image, or the first image of its gallery, linked to the page, with the page title as the caption. It replaced the legacy Child Pages block (photopress/childpages), removed in PhotoPress 2.0.
- WordPress 6.6 or later, and the block editor.
- A hierarchical post type, such as pages. The gallery shows children of the same post type as the page it is on.
- Edit the parent page.
- In the block inserter, choose Child Pages Gallery.
- Set the Pages panel, and the layout, slideshow and captions in the PhotoPress panel.
The editor shows no images. It shows a placeholder with a sentence such as "3 of the 4 pages under this one, each linked to it with its title, in the Masonry layout." In a template there is no page to count under, and the sentence says what the gallery will show.
The placeholder in the canvas describes what the gallery shows.
The Pages panel in the block settings sidebar.
| Control | What it does | Default |
|---|---|---|
| Show heading | Shows a heading above the pages when there are some | Off |
| Heading | The heading's text. Shown while Show heading is on | Pages |
| Image size | Medium, Large or Full size | Large |
The inserter adds the gallery with the first layout turned on in the Gallery tab and wide alignment. Hide captions in the PhotoPress panel hides the page titles.
A Child Pages Gallery on the front end, in the Rows layout.
- The children of the page being viewed, of the same post type.
- Published children only. Drafts, private, pending and scheduled pages are left out.
- In page order (the Order attribute), then by title.
- At most 100 pages.
- The page's featured image.
- Without one, the first image of the first gallery in the page's content (gallery::firstImage). Galleries nested in other blocks count. For a gallery that keeps its images, this is its first image block, or the first ID of a gallery saved before WordPress 5.9 or of the legacy PhotoPress Gallery block. For a dynamic gallery, it is the first image WordPress shows.
- A page with neither is left out.
Each image links to its page. The caption is the page title, also linked to the page. The gallery renders as a core Gallery block, so PhotoPress layouts and the slideshow apply. With no pages to show, the gallery renders nothing.
PhotoPress 2.0 removes the Child Pages block (photopress/childpages). On the first request after the update, a one-off background job converts each one saved in a post, page, template, template part or synced pattern into a Child Pages Gallery (GalleryUpgrade, convert). The conversion is an edit of the post, saved as a revision. It keeps the legacy block's settings:
| Legacy setting | Child Pages Gallery | Legacy default |
|---|---|---|
| Columns |
columns (core columns layout) |
2 |
| Image size | sizeSlug |
medium |
| Crop images | imageCrop |
On |
| Padding | Block spacing (style.spacing.blockGap) |
10 px |
| Alignment, additional CSS class | Kept | — |
A legacy block the job did not reach, such as one in a theme's template file or in content imported later, is rendered as the Child Pages Gallery it would become (render). The editor shows it as a block it does not support.
| Legacy Child Pages | Child Pages Gallery | |
|---|---|---|
| Image | Featured image only | Featured image, or the first image of the page's gallery |
| Page without an image | Shown as its title alone | Left out |
| Number of pages | All published children | Up to 100 |
| Layouts | Columns (Columns, Padding, Crop images) | Core columns or any PhotoPress layout |
| Slideshow | No | Yes |
| Hook | Type | Code | Purpose |
|---|---|---|---|
pre_render_block |
filter | ImageTemplates.php#L41 | Renders a core/gallery with photopressSource children (childPageItems) |
wp_after_insert_post |
action | ChildPagesGallery.php#L32 | Compares a saved page with its previous state and announces its parent (pageSaved) |
deleted_post |
action | ChildPagesGallery.php#L33 | A published page deleted: announces its parent |
photopress_post_changed |
action | ChildPagesGallery.php#L34 | With gallery in the context, a child page's gallery changed. Announces the parent when the child has no featured image. |
added_post_meta, updated_post_meta, deleted_post_meta
|
action | ChildPagesGallery.php#L36 |
_thumbnail_id changed: announces the parent |
pre_render_block |
filter | LegacyChildPages.php#L23 | Renders a legacy photopress/childpages block as its Child Pages Gallery |
wp_loaded |
action | GalleryUpgrade.php#L39 | Starts the gallery.upgrade job once per site (maybeStart) |
The job saves converted posts with serialize_blocks() and wp_update_post(), between kses_remove_filters() and kses_init(). The variation is registered in gallery-layouts.js#L204. Its editor UI is ChildPagesGalleryEdit.
childPageItems takes the parent from get_the_ID(), or get_queried_object_id() outside the loop. It returns nothing unless the parent's post type passes is_post_type_hierarchical(). It queries get_posts() with post_parent, post_status => publish, orderby => menu_order ASC, title ASC and numberposts => 100, and takes each image from get_post_thumbnail_id() or gallery::firstImage(). Each image block has linkDestination custom.
For a dynamic gallery, gallery::firstImage() calls core's block_core_gallery_resolve_dynamic_source() when it exists.
The block's settings are stored in the post's block markup. The edited-template check runs one query per request, over up to 100 published wp_template and wp_template_part posts.
| Data | Where | Lifetime |
|---|---|---|
photopress_gallery_upgrade |
Option: the version of the upgrade job that was started | Deleted on uninstall |
Proxy Cache Purge. On a site with a page cache and Proxy Cache Purge, PhotoPress purges a page whose Child Pages Gallery shows a changed child page. See Page Cache.
| Hook | Type | Arguments | When | Code |
|---|---|---|---|---|
photopress_post_changed |
action |
int $id, array $context (empty here) |
A page that shows its child pages has a child page that changed | ChildPagesGallery.php#L122, documented at GalleryAdd.php#L755 |
- The editor's count of pages shown is an estimate. It counts a child with a featured image, or with a gallery in its rendered content. The front end decides.
- A converted legacy block shows only child pages that have an image. The legacy block also listed pages without one, by title.
- A Child Pages Gallery placed in a post of a non-hierarchical type renders nothing.