PHPackages                             mediawikiext/highslidegallery - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. mediawikiext/highslidegallery

ActiveMediawiki-extension[Image & Media](/categories/media)

mediawikiext/highslidegallery
=============================

Leverages Highslide JS-powered galleries for images and YouTube videos: supports thumbnails or inline anchor text, slideshow grouping via hsgid and MediaWiki-style captions within an interactive overlay.

v2.1.0(4mo ago)06GPL-2.0JavaScriptPHP ^7.4 || ^8.0

Since Dec 9Pushed 4mo agoCompare

[ Source](https://github.com/z929669/HighslideGallery)[ Packagist](https://packagist.org/packages/mediawikiext/highslidegallery)[ Docs](https://gitlab.com/z929669/highslidegallery)[ RSS](/packages/mediawikiext-highslidegallery/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (1)Versions (3)Used By (0)

HighslideGallery (MediaWiki Extension)
======================================

[](#highslidegallery-mediawiki-extension)

HighslideGallery (HSG) leverages Highslide JS-powered overlays/slideshows for images and YouTube videos displayed as thumbnails or inline links on the page with titles and captions. Clicking a HSG thumbnail or link opens the image or video in an interactive overlay auto-sized to the viewport with ability to expand to full size with panning. See [this example](https://stepmodifications.org/wikidev/Template:Hsg).

> **Tested**:
>
> > v2.1.1 → MediaWiki 1.39 v2.1.0 → MediaWiki 1.39 v2.0.0 → MediaWiki 1.39 v1.3.0 → MediaWiki 1.39 v1.1.0 → MediaWiki 1.22 v1.0.0 → MediaWiki 1.17

Requirements / Compatibility
----------------------------

[](#requirements--compatibility)

- MediaWiki 1.39+ (ResourceLoader-only, modern hooks). Older MW versions are not supported in 2.0.0+.

Features
--------

[](#features)

- Thumbnails displayed by default at 210px with ability to size as needed, but inline links are optional using `inline=1`
- Toggle max resolution of images with panning - allows inspection of the entire image at native resolution, no matter the device screen size.
- Group images and YouTube videos into a single HSG gallery via `hsgid`.
- Support for opotional thumbnail layouts including justified tiling and clean arrangement in ordered/unordered lists
- Robust data model provides unique styling classes, maximizing compatibility with Mediawiki core media-handling and other media extensions.
- Thumb captions are default but optional with graceful caption fallbacks also used for image `alt` text.
- ResourceLoader-exposed i18n strings for hover instructions, control tooltips, loading text, and member counter
- Custom `LocalSettings.php` parameter allows positioning controls at bottom of viewport (default) or over the image expander (optional).
- Mobile (touch/tap) support with responsive layouts

Installation
------------

[](#installation)

If `$wgExtensionAssetsPath` is custom, update `hs.graphicsDir` in `modules/highslide.cfg.js` to match this path.

### Composer (recommended)

[](#composer-recommended)

Add to `composer.local.json`:

```
{
	"require": {
		"mediawikiext/highslidegallery": "^2.0"
	},
	"extra": {
		"merge-plugin": {
			"include": ["extensions/*/composer.json"]
		}
	}
}
```

Then run:

```
composer update mediawikiext/highslidegallery -W

```

This installs into `extensions/HighslideGallery/` from Packagist.

### Manual (archive)

[](#manual-archive)

1. Download a tagged release (e.g., `v2.0.0`) and extract to `extensions/HighslideGallery/`.
2. Ensure `extension.json`, `modules/`, and PHP sources are present.

### Registered hooks

[](#registered-hooks)

- `BeforePageDisplay` (injects Highslide core + RL modules)
- `ImageBeforeProduceHTML` (thumbnail handling)
- `ParserFirstCallInit` (tag/parser functions)
- `ResourceLoaderGetConfigVars` (JS config)

### Post-install

[](#post-install)

In `LocalSettings.php`:

```
wfLoadExtension( 'HighslideGallery' );
//$wgHSGControlsPreset = 'stacked-top'; # optional overlay config
```

#### If pages still have old CSS/JS after installing or updating

[](#if-pages-still-have-old-cssjs-after-installing-or-updating)

- Purge individual pages via ?action=purge
- Clear MediaWiki cache: php maintenance/rebuildLocalisationCache.php
- Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)

Usage
-----

[](#usage)

### Parser functions (modern)

[](#parser-functions-modern)

- Image (`#hsgimg`): `{{#hsgimg:source=File:Pic.jpg|hsgid=GalleryA|width=210|title=Title|caption=Caption|inline=0|nocaption=0|linktext=Inline link text}}`
- YouTube (`#hsgytb`): `{{#hsgytb:source=VIDEO_ID|hsgid=GalleryA|width=210|title=Title|caption=Caption|inline=0|autoplay=0}}`

Parameters (named; positional `source` is also accepted):

- `source` (required): `File:Title` or external URL (image) / YouTube ID or URL (video).
- `hsgid` (optional): slideshow gallery ID; alphanumeric with optional dashes, underscores, and forward slashes (e.g., `GalleryA`, `Gallery-1`, `Section_1/Subsection`). IDs must not contain spaces or other special characters. Multiple items with the same `hsgid` form a slideshow group.
- `width` (optional): max thumb width in px (default 210).
- `tile` (optional): truthy → enforce horizontal tiling (adds `hsg-tiles-horizontal` to the auto wrapper).
- `title` (optional): overlay title text.
- `caption` (optional): overlay caption text.
- `nocaption` (optional): truthy → hides thumb caption (overlay caption still shown).
- `inline` (optional): truthy → inline link; falsy/omitted → thumbnail (default).
- `linktext` (optional): inline link text (inline only).
- `autoplay` (YouTube only): truthy → enables autoplay (muted).

### Examples using the raw parser functions directly

[](#examples-using-the-raw-parser-functions-directly)

- Inline image with custom link text: `{{#hsgimg:source=File:Pic.jpg|hsgid=Some_gallery|inline=1|linktext=this image|title=Some title|caption=Some caption}}`
- Mixed gallery (images + video) with captions and default thumbs: `{{#hsgimg:source=File:Pic1.jpg|hsgid=GalleryMixed|title=Title1|caption=Caption1}}``{{#hsgimg:source=File:Pic2.jpg|hsgid=GalleryMixed|title=Title2|caption=Caption2}}``{{#hsgytb:source=VIDEO_ID|hsgid=GalleryMixed|title=Clip|caption=Some video}}`

### Example template leveraging all features

[](#example-template-leveraging-all-features)

```

{{#if: {{{ytb|}}}
|
{{#hsgytb:
| source={{{ytb|}}}
| hsgid={{{hsgid|}}}
| tile={{{tile|0}}}
| width={{{width|}}}
| title={{{title|}}}
| caption={{{caption|}}}
| nocaption={{{nocaption|0}}}
| inline={{{inline|0}}}
| linktext={{{linktext|}}}
| autoplay={{{autoplay|}}}
}}
|
{{#hsgimg:
| source={{{img|}}}
| hsgid={{{hsgid|}}}
| tile={{{tile|0}}}
| width={{{width|}}}
| title={{{title|}}}
| caption={{{caption|}}}
| nocaption={{{nocaption|0}}}
| inline={{{inline|0}}}
| linktext={{{linktext|}}}
}} }}

```

### Understanding Content Types & Galleries

[](#understanding-content-types--galleries)

HSG supports three types of content, all of which can coexist in a single slideshow gallery:

#### Internal Wiki Files (`[[File:…]]` or `[[Image:…]]`)

[](#internal-wiki-files-file-or-image)

Use the `{{#hsgimg:…}}` parser function to integrate internal wiki files into HSG galleries. While MediaWiki's native `[[File:Example.jpg|thumb|…]]` syntax still works, it renders standard MediaWiki thumbnails without HSG functionality. To use HSG with internal files, pass the file title to `{{#hsgimg:source=File:Example.jpg|hsgid=GalleryA|…}}` instead. Internal files, external images, and YouTube videos can exist in the same slideshow by using the same `hsgid=`.

#### External Images (`{{#hsgimg:…}}`)

[](#external-images-hsgimg)

Use the parser function for images not stored on the wiki (arbitrary external URLs). These can be grouped with the same `hsgid=` as internal files or YouTube videos to create mixed-content galleries.

#### YouTube Videos (`{{#hsgytb:…}}` or `…`)

[](#youtube-videos-hsgytb-or-hsgytbhsgytb)

Embed videos either as inline text links or thumbnail previews (using the YouTube preview image from `img.youtube.com`). The `inline=` parameter controls this. Videos can be grouped into the same `hsgid=` as images.

#### Gallery Grouping

[](#gallery-grouping)

When multiple media items share the same `hsgid=`, they form a single slideshow group. The viewer opens one item and can navigate to others in that group using the slideshow controls. This works across content types. I.e., a gallery works with internal images, external images, and YouTube videos all grouped under `hsgid=MyGallery`.

---

### Tiling layouts (opt-in)

[](#tiling-layouts-opt-in)

- Default thumbs are resizable using custom `width=#` (px). To tile responsively (i.e., 'justified' thumbs), set `tile=1` on all thumbs that declare a common `hsgid`; the auto wrapper gets `hsg-tiles-horizontal`. Control sizing with CSS variables, `--hsg-tile-min` and `--hsg-tile-gap`, in `highslide.override.css`.
- Inline `width=` values on thumbs are otherwise overridden inside the tiling wrappers.

### Legacy tags (still supported)

[](#legacy-tags-still-supported)

- YouTube tag: `https://www.youtube.com/watch?v=VIDEO_ID` (defaults to inline). Prefer `#hsgytb` for modern usage.
- **Note**: The extension no longer accepts `[[File:…|hsgid=…]]` syntax to invoke HSG; use `{{#hsgimg:source=File:…|hsgid=…}}` instead. Legacy `hsgid=/highslide=` prefixes in captions are parsed for backward compatibility but do not activate HSG on native file links.

Guarantees
----------

[](#guarantees)

- **Image clicks do not close overlays** — Viewers must use the close button, press Esc, or click the dimmed margin to close. This prevents accidental exits when interacting with the image.
- **Clean HTML** — HSG prevents malformed captions and ensures consistent markup. External and internal images both get proper `alt` text and title attributes.
- **Responsive overlays** — Overlays auto-fit to the viewport with sensible margins (configurable at the top pf `highslide.cfg.js), and images can be zoomed to full size with panning.
- **Gallery index** — When viewing a multi-image gallery, the overlay displays "1 of N" so viewers know their position.

Limitations
-----------

[](#limitations)

- **Zoom UI controls** — The zoom helper exists and works programmatically, but manual UI buttons (zoom in/zoom out) are not wired into the overlay, nor are there plans to do so unless the need arises. Possible workaround: use keyboard or browser zoom.
- **Caption HTML detection** — HSG uses a simple heuristic to detect HTML in captions. If captions have unusual formats, they may not render as expected. For complex HTML, consider using a template.

Configuration
-------------

[](#configuration)

- `$wgHSGControlsPreset = 'stacked-top';` in `LocalSettings.php` for alternate control/thumbstrip positioning. Comment or set to `classic` for default positioning below media.
- `modules/highslide.cfg.js` for overlay behavior (margins, zoom, controls).
- `modules/highslide.override.css` for styling (SVG controls, thumbstrip, captions).

Defaults require no manual changes.

Compatibility with Other MediaWiki Features
-------------------------------------------

[](#compatibility-with-other-mediawiki-features)

- **MediaViewer** — HSG thumbnails are automatically marked with the `noviewer` class to prevent MediaViewer from interfering with HSG overlays. HSG completely replaces MediaViewer for images created via `{{#hsgimg:…}}`.
- **Standard MediaWiki `[[File:…]]` syntax** — Native MediaWiki file links continue to work as usual and are not affected by HSG. Use `{{#hsgimg:…}}` to enable HSG popups for internal files.
- **Other galleries** (`` tag, etc.) — HSG does not interfere with other gallery implementations; the extension targets only media created via its parser functions.

Customization via JS and CSS Variables
--------------------------------------

[](#customization-via-js-and-css-variables)

HSG exposes several convenience variables and CSS custom properties (CSS variables) that can be adjusted via custom styles or LocalSettings without modifying extension code. This prevents conflicts and makes updates safe.

### JavaScript Configuration (`modules/highslide.cfg.js`)

[](#javascript-configuration-moduleshighslidecfgjs)

The following `hs.*` properties are exposed and can be overridden via custom JS:

**Overlay behavior:**

- `hs.align` (default: `'center'`) — Horizontal alignment of the overlay
- `hs.marginTop`, `hs.marginBottom`, `hs.marginLeft`, `hs.marginRight` (px) — Viewport margins around overlay
- `hs.dimmingOpacity` (default: 0.75) — Opacity of the background dimmer (0–1)
- `hs.closeOnClick` (default: false) — Whether clicking the image closes the overlay (HSG forces false to prevent accidental closes)
- `hs.allowSizeReduction` (default: true) — Allow shrinking overlays to fit viewport
- `hs.showCredits` (default: false) — Show Highslide credits in overlay
- `hs.outlineType` (default: null) — Outline style; HSG uses CSS-driven styling

**Transitions (can be toggled for different effects):**

- `hs.restoreDuration` (d)efault: 250) — Duration of zoom out on closing the overlay
- `hs.expandDuration`, `hs.restoreDuration` (default: 0 ms) — Animation timing
- `hs.transitions` (default: \[\]) — Array of transition effects; try `['expand', 'crossfade']` for classic behavior
- `hs.transitionDuration` (d)efault: 250) — duration of ANY enabled transitions/animations of images, captions, or overlay

**Gallery display:**

- `hs.numberPosition` (default: `'caption'`) — Where "1 of N" appears (`'caption'`, `'top-left'`, `'bottom-left'`, etc.)
- `hs.wrapperClassName` (default: `'hsg-frame floating-caption'`) — CSS classes applied to the overlay wrapper

**To override**, add JavaScript to LocalSettings.php or custom JS file *after* HighslideGallery is loaded:

```
// Example: Increase margins, enable fade transitions
if (typeof hs !== "undefined") {
	hs.marginTop = 60;
	hs.marginBottom = 60;
	hs.expandDuration = 200;
}
```

### CSS Custom Properties (`modules/highslide.override.css`)

[](#css-custom-properties-moduleshighslideoverridecss)

The following CSS variables are defined in `:root` and can be overridden via custom CSS stylesheet:

**Colors:**

- `--hsg-caption-number` (default: #777) — Gallery index text ("1 of 5") color
- `--hsg-caption-gallery` (default: #b0b0b0) — Gallery title color
- `--hsg-caption-title` (default: #b0b0b0) — Overlay title color
- `--hsg-caption-caption` (default: #ff9012) — Overlay caption text color
- `--hsg-caption-text` (default: #777) — General overlay text color
- `--hsg-caption-thumb-title`, `--hsg-caption-thumb-caption`, `--hsg-caption-thumb-text` — Thumbnail caption colors

**Frame and layout:**

- `--hsg-dimmer` (default: rgba(0, 0, 0, 0.75)) — Background dimmer color and opacity
- `--hsg-frame-bg` (default: #000) — Overlay frame background color
- `--hsg-frame-border` (default: #888) — Frame border color
- `--hsg-frame-shadow` (default: rgba(0, 0, 0, 0.9)) — Frame shadow color
- `--hsg-ytb-bg` (default: #000) — YouTube embed background

**Responsive tiling:**

- `--hsg-tile-min` (default: 210px) — Minimum thumbnail width in responsive tiling layouts (when `tile=1`)
- `--hsg-tile-gap` (default: 12px) — Gap between tiled thumbnails

**Thumbnails and controls:**

- `--hsg-ts-border` (default: #ff9012) — Thumbstrip (slideshow navigation) border color
- `--hsg-ts-border-hover` (default: #aaa) — Thumbstrip border color on hover

### Beware modifications to the following

[](#beware-modifications-to-the-following)

- `hs.graphicsDir` — Set this in `highslide.cfg.js` if `$wgExtensionAssetsPath` is custom (see Installation section)
- `hs.wrapperClassName` — HSG requires `'hsg-frame'` for proper styling; modify CSS instead of this property
- `hs.closeOnClick` — HSG forces this to `false` for UX; modifying it will break expected behavior
- Any vendor properties from `modules/highslide-full.js` not listed above — these are internal to Highslide and changes may cause unexpected behavior

Contributing
------------

[](#contributing)

Merge requests and issues:

License
-------

[](#license)

- **Extension code**: GPL-2.0
- **Bundled library (`modules/highslide-full.js`/assets)**: MIT (license notice retained; MIT code shipped within a GPL-2.0 project is compatible).

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance75

Regular maintenance activity

Popularity5

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 90.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~14 days

Total

2

Last Release

140d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/95c5bdbc9ae4bd50e70eb1612f22fa583feba7ec9b376ebe77df617b065b6f1e?d=identicon)[z929669](/maintainers/z929669)

---

Top Contributors

[![z929669](https://avatars.githubusercontent.com/u/1461913?v=4)](https://github.com/z929669 "z929669 (58 commits)")[![kodene](https://avatars.githubusercontent.com/u/1867652?v=4)](https://github.com/kodene "kodene (6 commits)")

---

Tags

mediawikiyoutubeimagesextensiongallerylightboxhighslide

### Embed Badge

![Health badge](/badges/mediawikiext-highslidegallery/health.svg)

```
[![Health](https://phpackages.com/badges/mediawikiext-highslidegallery/health.svg)](https://phpackages.com/packages/mediawikiext-highslidegallery)
```

###  Alternatives

[nicolafranchini/venobox

Responsive JavaScript modal window plugin, touch swipe gallery

7106.8k](/packages/nicolafranchini-venobox)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)