Repository navigation
Full Screen Slideshow
A gallery with Slideshow on opens a full-screen slideshow when a visitor clicks one of its images. The slideshow fills the window over the page, with optional thumbnails and a box for each image's caption and details.
- WordPress 6.6 or later.
- Slideshows switched on in PhotoPress › Settings › Slideshow (on by default).
- A core Gallery block with Slideshow on, in any layout, or a legacy PhotoPress Gallery block with Slideshow on.
- Block themes and classic themes both work. The theme must call
wp_footer(), where the slideshow's container is printed. - No jQuery or carousel library. The slideshow is one script with no dependencies.
Open PhotoPress › Settings and choose the Slideshow tab. Switches and sliders save when you change them. Attachment Link Text saves with its Save button.
The Slideshow tab.
| Control | What it does | Default |
|---|---|---|
| Slideshows | Opens the full-screen slideshow when an image in a gallery with Slideshow on is clicked. Off, no gallery opens it. | On |
| Thumbnails | A row of thumbnails along the bottom of the slideshow. | On |
| Thumbnail Height | Height of the thumbnails, 75–200 px in steps of 10. Shown while Thumbnails is on. | 120 |
| Caption | The image's caption, in the caption info box. | On |
| Title | The image's title. | Off |
| Description | The image's description. | Off |
| Link to the image's page | A link to the image's attachment page. | Off |
| Attachment Link Text | The text of that link. Cannot be empty. Shown while Link to the image's page is on. | Read More... |
| Caption Info Box Position | Bottom of image or Right of image. Shown while any of the four switches above is on. | Bottom of image |
| Caption Padding (px) | Space around the caption area, 0–100 px. Shown while any of the four switches above is on. | 0 |
Caption, Title, Description and Link to the image's page are independent, under the Caption info heading. The box is shown when an image has at least one of the items turned on.
- Open PhotoPress › Settings › Slideshow and check that Slideshows is on.
- In the editor, select a Gallery block.
- In the block sidebar, open the PhotoPress panel and turn on Slideshow.
- Update the post.
For a legacy PhotoPress Gallery block, turn on Slideshow in its own sidebar.
A gallery with Slideshow on. Clicking an image opens the slideshow at that image.
The slideshow on a desktop, with the caption info below the image.
- A click anywhere on a gallery item, including its caption, opens the slideshow at that image.
- A click with Ctrl, ⌘, Shift or Alt held on an image that links somewhere (Link to set to the media file or attachment page) is left to the browser, which opens the link in a new tab or window. On an image with no link, it opens the slideshow.
- The slideshow covers the window. The page behind it does not scroll.
- Close, in the top right corner, closes it. So does the Escape key.
- Reopening the same gallery jumps straight to the clicked image. Clicking an image in another gallery builds that gallery's slideshow.
- One slideshow container serves every gallery on the page.
| Input | Action |
|---|---|
| Mouse press on the left half | Previous image. A large chevron at the pointer shows the direction. |
| Mouse press on the right half | Next image. |
| Swipe left or right (touch) | Next or previous image. The swipe must be more than 40 px and more horizontal than vertical. |
| Tap on the left or right half (touch) | Previous or next image. The chevron shows for a moment where the tap landed. |
| Left and Right arrow keys | Previous and next image, from anywhere on the page while the slideshow is open, except in a form field. |
| Tab | Moves between the slideshow, Previous image, Next image, links in the caption, the thumbnails and Close. |
| Click on a thumbnail | Shows that image. |
The mouse navigates on the press, not on release, so holding the button does not select text or drag the image. Links in the caption, and the thumbnails, keep their own behavior. Going from the last image to the first, or back, is instant. Other changes slide.
The chevron at the pointer shows which way a press goes.
The thumbnail row sits under the slides. The current thumbnail is marked and scrolled to the middle of the row. Thumbnails load lazily, each from the image's srcset at the thumbnail width.
The thumbnail row, the current image's thumbnail at full opacity.
The box shows, in order: the title, the caption, the description and the link, each when its setting is on and the image has it. The title is bold.
- Bottom of image: centered under the image.
- Right of image: beside the image, level with its bottom edge. In a window 600 px wide or less, the box goes below the image.
Caption Info Box Position set to Right of image.
On a phone, the caption info is always below the image.
The caption is the image's Media Library caption. When that is empty, it is the caption under the image in the gallery, even with Hide captions on.
- Each slide first shows the copy of its image the page has already loaded, at the size of the full image. The browser then loads the file its
srcsetpicks for the width shown. - The current slide and the slides on either side are loaded. Others load as they come near.
- Each slide's
sizesis set to the width the image is shown at, and updated when the window is resized or a phone is turned.
- The container is a dialog:
role="dialog",aria-modal="true", labeled "Slideshow". - While it is open, everything else in
<body>is madeinert: out of reach of Tab, clicks and screen readers. Only what the slideshow made inert is restored on close. - Focus moves to the slideshow on open and returns to the element it was opened from on close.
- Each change of image is announced in a polite live region as "3 / 12".
- For visitors who ask for reduced motion, images change without the slide transition.
| Hook | Type | Code | Purpose |
|---|---|---|---|
render_block |
filter | slideshow.php#L38 | For core/gallery with photopressSlideshow, or photopress/gallery with linkToSlideshow: adds the photopress-has-slideshow class, adds the images' data-* attributes, and queues the script, styles and container once per page. Added only while Slideshows is on (L27). |
wp_footer |
action | slideshow.php#L85 | Prints the container #lightbox-gallery, with the settings and control labels as data-* attributes and the caption padding as --pp-slideshow-caption-padding. |
render_block_core/gallery |
filter | gallery.php#L231 | Marks each image item photopress-gallery-item, with data-position and data-id. The script opens the slideshow from these. |
render_block_data |
filter | gallery.php#L84 | Loads a slideshow gallery's images and metadata in one query. |
wp_loaded |
action | PageCache.php#L334 | Empties the page cache once after a PhotoPress update. See Third-party integrations. |
One script, dist/gallery-slideshow.build.js (handle photopress-gallery-slideshow), runs the full-screen slideshow and the Gallery Slideshow Block. It is registered with wp_register_script() in the footer with defer and no dependencies (gallery.php#L42), and enqueued only on pages with a slideshow gallery (slideshow.php#L139).
| Source | Does |
|---|---|
| src/frontend/lightbox.js | Opens and closes the dialog, builds the slides from the clicked gallery's images, makes the page inert. |
| src/shared/slideshow.js | The slideshow itself: slides, loading, sizes, thumbnails, arrow keys. Shared with the Gallery Slideshow block. |
| src/shared/press-navigation.js | Press, swipe and tap navigation, and the chevron. |
| src/shared/styles/slideshow.scss | Styles of the full-screen slideshow only. The rest are the Gallery Slideshow block's (style.scss). Both are in photopress-frontend (dist/blocks.style.build.css). |
metadata::addAttributesToImagesInContent() adds these attributes to each <img> of a slideshow gallery. Only the slideshow reads them.
| Attribute | Value | Kind |
|---|---|---|
data-orig-file |
The full-size file, from wp_get_attachment_image_src()
|
url |
data-attachment-url |
The image's page, from get_attachment_link()
|
url |
data-aspectratio |
Width ÷ height from wp_get_attachment_metadata(), two decimals |
number |
data-caption |
The Media Library caption, through wptexturize()
|
html |
data-image-title |
The title, through wptexturize()
|
html |
data-image-description |
The description, through wptexturize() and wpautop()
|
html |
(code)
Sanitization:
- An attribute already in the post's markup is kept, so a value the block saved (the legacy gallery's
data-caption) wins over the Media Library's. - Each such existing value is cleaned by
metadata::safeAttribute(): url throughesc_url_raw()withhttpandhttpsonly. A number is kept only if it is numeric. html goes throughwp_kses_post(). - In the browser, the title, caption and description are parsed in a separate document, and scripts, styles, frames, objects, forms, event handler attributes and
javascript:,data:andvbscript:addresses are removed before they are shown (lightbox.js#L78). - The link is shown only for an
httporhttpsaddress.
-
WP_HTML_Tag_Processorfor every change to the rendered gallery. -
wp_enqueue_script()andwp_enqueue_style(). -
register_setting()withshow_in_rest. The tab reads and writes the settings through/wp/v2/settings.
| Where | Name | Contents |
|---|---|---|
| Option | photopress_core_slideshow |
enable, showThumbnails, thumbnailHeight, showCaptions, detail_position (bottom or right), captionPadding, showTitleInCaption, showDescriptionInCaption, showAttachmentLink, attachmentLinkText. |
| Option | photopress_version |
The PhotoPress version the page cache was last emptied for. |
Block comment of core/gallery
|
photopressSlideshow |
Boolean, default false. |
Block comment of photopress/gallery
|
linkToSlideshow |
Boolean, default false. |
| Cached page from | What happens |
|---|---|
| Before 2.0 | The page asks for modules/slideshow/assets/js/slideshow.js, after jQuery and Owl Carousel. That file now loads dist/gallery-slideshow.build.js in its place (code). |
| 1.6 or earlier | The galleries lack the photopress-has-slideshow class. On a click, if no gallery on the page has it, every .photopress-gallery on the page opens the slideshow, as in 1.6 (code). |
See also Page Cache.
PhotoPress uses only Proxy Cache Purge's documented filters. It adds its event photopress_purge_all to varnish_http_purge_events and varnish_http_purge_events_full (PageCache.php#L102). On the first request after PhotoPress is updated, it compares the photopress_version option with the running version and fires that event once, which empties the whole cache (PageCache.php#L334).
Without Proxy Cache Purge, or with it inactive, PhotoPress empties no cache. The option is still updated. Cached pages are then handled by the loader and the 1.6 fallback above.
These are DOM events, dispatched by the script.
| Event | Dispatched on | Bubbles | When | Code |
|---|---|---|---|---|
pp-slideshow-opened |
#lightbox-gallery |
Yes | The slideshow has opened. | lightbox.js#L210 |
pp-slideshow-closed |
#lightbox-gallery |
Yes | The slideshow has closed. | lightbox.js#L224 |
photopress-slideshow-change |
The slideshow's .photopress-gallery-slideshow element |
No | The current image changed. event.detail.index is its position, from 0. Also fired when the slideshow is built. |
slideshow.js#L286 |
- Slideshow on a gallery has no effect while Slideshows is off in the Slideshow tab.
- The Media Library caption is shown in place of a different caption typed in the gallery. The gallery's caption is used only when the Media Library caption is empty.
- With attachment pages off in the Pages & Search tab (Attachment and Taxonomy Pages), Link to the image's page links to the image file.
- The full-screen slideshow always uses the slide transition and has no autoplay.