Extension:HighslideGallery

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki extensions manual
Crystal Clear action run.svg
HighslideGallery
Release status: stable
Implementation Tag, Parser function
Description HighslideGallery uses Highslide JS to enable images and YouTube videos to be displayed in an image gallery.
Author(s) Brian McCloskey (Kodenetalk)
Latest version 1.0.0 (2012-10-22)
MediaWiki 1.17.0 to 1.23
License GPLv2
Download from GitHub
Example http://wiki.step-project.com/HighslideGallery/Sandbox
Tags
<hsyoutube>
Hooks used
ImageBeforeProduceHTML
BeforePageDisplay
ParserFirstCallInit
Translate the HighslideGallery extension if it is available at translatewiki.net
Check usage and version matrix.

The HighslideGallery extension uses Highslide JS to enable images and YouTube videos to be displayed in an image gallery. HighslideGallery differs from other image gallery extensions in that users have control for when an image should be included in a gallery, as well as being able to define separate galleries within the same page. In order to enable a local image to be a part of a gallery, information must be added to the caption field of an [[Image:]] function (details below).

This extension does not enable highslide automatically for images defined in a page. If that is your goal you should look into some of the other image gallery extensions. This extension was born out of a desire to have a choice of when to have an image display in a gallery, while still having the image rendered in page by MediaWIki. All processing occurs during the parsing phase when a page is saved, so Highslide enabled images are cached instead of having to parse the HTML before render on every page view.

News[edit]

This extension breaks with MediaWiki 1.24 due to use of a now deprecated function in Linker that passes null as the parser object. A new version is currently being tested on 1.25.2. See the Talk page for more information.

Installation[edit]

Extract the archive into the extensions folder in MediaWiki which should result in a directory structure of extensions/HighslideGallery. This extension does not include Highslide JS, which can be obtained from the following website:

http://www.highslide.com/

Download the latest zip file containing the Highslide JS distribution. This extension uses ResourceLoader to load the javascript and CSS files, so either the full source or the minified versions can be used. The only resources that are needed are the following:

  • highslide/graphics (directory)
  • highslide/highslide-full.js (or) highslide-full.min.js
  • highslide/highslide.css

The above resources should be copied from within the highslide/ directory, into the following location:

extensions/HighslideGallery/modules/

which should result in the following:

  • extensions/HighslideGallery/modules/graphics/
  • extensions/HighslideGallery/modules/highslide-full.js
  • extensions/HighslideGallery/modules/highslide.css

Whichever version of the Highslide JS was chosen (full source or minified), the file needs to be renamed to highslide.js so that the ResourceLoader can load it.

To enable the HighslideGallery extension, add the following line to LocalSettings.php:

require_once("$IP/extensions/HighslideGallery/HighslideGallery.php");

Usage[edit]

This extension allows enabling a Highslide gallery on images stored locally in MediaWiki, on external images using a parser function, and on YouTube videos using a tag. A Gallery ID can be assigned to images to allow multiple separate galleries on the same page. Syntax on each of these methods is detailed in the following sections.

Local Image Galleries[edit]

Enabling a local image to be a part of a Highslide gallery requires adding syntax to the caption field of the [[Image:]] function. The two methods are highslide: which adds the image to its own gallery, and highslide=ID: which allows adding multiple images to the same gallery. Multiple galleries can be included in the same page by adding images to a different gallery ID (ID's must only contain letters and/or numbers). Local images are still rendered in page by MediaWiki as determined by the Image parameters.

Example for single images in their own gallery (the second example ends up with no caption text):

[[Image:image001.png|100|highslide:Caption for Image 1]]
[[Image:image002.png|100|left|highslide:]]

Example for multiple images contained within their own gallery:

[[Image:image001.png|100|highslide=1:Caption for Image 1, which is in Gallery 1]]
[[Image:image002.png|100|highslide=1:Caption for Image 2, which is in Gallery 1]]
[[Image:image003.png|100|highslide=1:Caption for Image 3, which is in Gallery 1]]
[[Image:image004.png|100|highslide=2:Caption for Image 4, which is in Gallery 2]]
[[Image:image005.png|100|highslide=2:Caption for Iamge 5, which is in Gallery 2]]

In the above example, there will be two galleries on the page. Gallery 1 will only contain three images, and Gallery 2 will only contain two images.

The magnify icon is also placed next to the caption when viewing in the gallery to provide an easy means of going to the Image description page.

External Image Galleries[edit]

To include images from an external site into galleries, the {{#hsimg}} parser function is used. The syntax is as follows:

{{#hsimg:<id>|<width>|<title>|<url>}}

The parameters are described below.

  • id (optional) - Specifies a gallery ID. This can be a gallery ID already assigned to a local image such that they share the same gallery. If not set, it will be the only image contained within its own gallery.
  • width (optional) - Specifies the max width for the image in page.
  • title (optional) - Specifies a title for the image which is then used for the caption within the gallery. If this is not set, the caption reverts to the URL of the image.
  • url (required) - Specifies the URL to the image.

Example:

{{#hsimg:1|100|External Image 1|http://somebogusexamplesite.com/image001.png}}

YouTube Links[edit]

YouTube videos can be included in a highslide gallery. Instead of displaying the embedded video player in the page, a link is created to the YouTube video which opens in a Highslide gallery when clicked. If you want the player embedded in page, there are other extensions available for that purpose.

The syntax for adding a YouTube link:

<hsyoutube title="Link text" caption="Caption for the video" autoplay>http://www.youtube.com/watch?v=aHjpOzsQ9YI</hsyoutube>

The URL to the video can be copied directly form the address bar from YouTube. The parameters title, caption, and autoplay are optional. If title is set, it becomes the link text, otherwise "YouTube video" is used. If caption is set, it becomes the caption displayed in the Highslide gallery. If autoplay is defined, the video will begin playing automatically when opened.

See also[edit]