Each Gallery has a Custom JavaScript field where you can write JavaScript that runs in the context of that Gallery. Use it to hook into Gallery events, modify behaviour after the Gallery renders, or integrate with third-party scripts.
Location Gallery Editor → Settings → Custom Code → Custom JavaScript
How it works #
JavaScript entered in this field is executed after the gallery has been initialised on the page. The gallery’s wrapper element is available in the DOM at the time the script runs.
Security restrictions #
By default, FotoGrids blocks the following constructs in custom JavaScript fields:
eval()Function()constructor- String-based
setTimeoutandsetInterval
These are blocked to protect against accidental or malicious use by lower-privilege users who have Gallery editing access. Administrators are never restricted.
If you have a specific need for dynamic code execution and trust all users with Gallery editing rights, an administrator can lift this restriction globally at FotoGrids → Settings → Advanced → Allow Dynamic Execution.
| Setting | Allow Dynamic Execution |
| Options | On Off |
| Default | Off |
When enabled, eval, Function, and string-based timer calls are permitted in custom JavaScript fields across all Galleries. This setting applies to all roles that can edit Galleries, except administrators, who are never restricted regardless of this setting.
Only enable this if you fully trust everyone who has Gallery editing access on your site. Dynamic execution allows editor-level users to run arbitrary JavaScript on your frontend, which is a potential XSS vector if those accounts are compromised or misused.
Global Custom JavaScript Pro #
Per-Gallery JavaScript is useful for targeted behaviour, but some scripts belong everywhere — an analytics event listener, a custom sharing integration, or a script that hooks into the Lightbox across your entire site. FotoGrids Pro includes a Global Custom JavaScript field that runs your code after every Gallery initialises on any page, without needing to add it to each Gallery individually. The same security restrictions apply as the per-Gallery field, keeping your site safe while giving you the flexibility to build on top of FotoGrids at scale.
Tips #
Avoid blocking or synchronous DOM operations — Gallery initialisation is asynchronous and time-sensitive. If you need to react to Gallery events (item click, Lightbox open, etc.), listen for the custom events FotoGrids fires rather than using timers to poll the DOM.
The Custom JavaScript field is not a replacement for a site-wide plugin or a functions.php custom script. For complex integrations, a dedicated plugin or theme code is more maintainable than per-gallery JavaScript across many Galleries.
