Phoca Gallery PhotoSwipe – Joomla Page Break Fix
A small Joomla system plugin to work around two PhotoSwipe problems encountered when using Phoca Gallery galleries inside articles with Joomla Page Breaks.
Environment
- Joomla 6.1.4
- Phoca Gallery 6.1.5
- Phoca Gallery Button Plugin 6.1.1
- Phoca Gallery Content Plugin 6.1.1
The problems
1. PhotoSwipe only works on the last gallery page
When a Joomla article is split across multiple pages using Page Breaks, a Phoca Gallery gallery can appear correctly on more than one page, but the PhotoSwipe root element (.pswp) is only present on the page containing the last gallery.
For example:
/dev/article-info?start=6
contains a working gallery grid but no .pswp element, while:
/dev/article-info?start=7
contains both the gallery and the PhotoSwipe container.
Clicking an image on the earlier page consequently produces JavaScript errors such as:
Uncaught TypeError: Cannot read properties of undefined (reading 'firstChild')
The problem is caused by the PhotoSwipe container being inserted into paginated article content. Joomla's Page Break processing means that the container is not necessarily present on every page containing a gallery.
2. PhotoSwipe loses the Joomla Page Break URL when closing
When an image is opened on a paginated page, PhotoSwipe correctly adds its gallery information to the URL:
/dev/article-info?start=7#&gid=1&pid=1
This is useful because individual images can be linked directly.
However, when PhotoSwipe is closed, its history handling can remove the Joomla query string as well, leaving:
/dev/article-info
instead of returning to:
/dev/article-info?start=7
This causes the user to be returned to the wrong article page.
The solution
The final solution is a small standalone Joomla system plugin:
NX Phoca PhotoSwipe Fix
The plugin leaves Phoca Gallery and PhotoSwipe untouched.
It performs two independent fixes:
- Missing PhotoSwipe container: If a page contains a Phoca Gallery PhotoSwipe gallery but no
.pswpcontainer, the plugin supplies the required PhotoSwipe markup immediately before</body>. - Preserving the Joomla Page Break URL: The plugin remembers the original query string, such as
?start=7, and intercepts the browser History API used by PhotoSwipe so that the Joomla query string is retained while the PhotoSwipe gallery hash is added and removed.
The resulting behaviour is:
/dev/article-info?start=7 ↓ /dev/article-info?start=7#&gid=1&pid=1 ↓ /dev/article-info?start=7
Installation
Install the NX plugin through the normal Joomla extension installer and enable:
System - NX Phoca PhotoSwipe Fix
No modifications to Phoca Gallery or PhotoSwipe are required.
Download
NX Phoca PhotoSwipe Fix
Joomla system plugin — site-specific compatibility workaround.
Important
This is a workaround for the interaction between Joomla article pagination, Phoca Gallery and PhotoSwipe. It is deliberately implemented as a separate system plugin so that updates to Phoca Gallery or PhotoSwipe do not overwrite the fix.
Phoca Gallery's original PHP and JavaScript files should remain unchanged.
Documented after debugging the issue on Joomla 6.1.4 / Phoca Gallery 6.1.5. The plugin was developed specifically to avoid modifying third-party extension files.