Extension:SmoothGallery

From MediaWiki.org

**Manual on MediaWiki Extensions**
**List of MediaWiki Extensions**
SmoothGallery Release status: experimental
Implementation	Tag
Description	Allows users to give a delimited list of images, and output a css/javascript gallery.
Author(s)	Ryan Lane
Version	1.0h (2007-02-03)
MediaWiki	1.7+ (or 1.6+, see Installation notes)
Download	svn (1.0h) svn (1.1c beta)
Hooks used	OutputPageParserOutput

This is an extension that integrates JonDesign's SmoothGallery, which is a set of Javascript and CSS that lets you make picture galleries. A number of features are available from SmoothGallery, and this extension aims to be an easy to use, and full featured integration with MediaWiki. JonDesign's SmoothGallery is released under the GPL.

[edit] Usage

[edit] Arguments

The following arguments are available to change the behavior of the gallery:

width: A greater than zero number in pixels to modify the width of the gallery.
height: A greater than zero number in pixels to modify the height of the gallery.
showarrows: Set to "false" to disable the showing of the arrow buttons.
showcarousel: Set to "false" to disable the carousel.
showinfopane: Set to "false" to disable the infopane.
timed: Set to "true" to make a timed slideshow.
delay: A greater than zero number in milliseconds to change the delay when using a timed slideshow.
special: Create a link to a special page; this will allow you to link to galleries instead of embedding them. The number of images available for this type of gallery will be restricted by the length of a url.

[edit] Syntax examples

To make a basic gallery, put a line break delimited list inside of <sgallery></sgallery> tags like so:

<sgallery>
Image1.jpg
Image2.gif
Image3.png
</sgallery>

To make a timed slideshow without the carousel, arrow buttons, and infopane; and with a width of 600px, a height of 500px, and a delay of 4000ms; you would do the following:

<sgallery width="600" height="500" showarrows="false" showcarousel="false" showinfopane="false" timed="true" delay="4000">
Image1.jpg
Image2.gif
Image3.png
</sgallery>

To make a link called "Hey look, a link!" to a special page with the previous gallery:

<sgallery special="Hey look, a link!" width="600" height="500" showarrows="false" showcarousel="false" showinfopane="false" timed="true" delay="4000">
Image1.jpg
Image2.gif
Image3.png
</sgallery>

The extension will make thumbnails for the carousel, and for images that do not fit in the gallery. When a user clicks an image in the carousel, it will bring he/she to the image's wiki page. The infopane uses the image name as the image title, and the image's description from the image page as the description. Images that are missing or typo'd will be ignored by the gallery. If all images are missing, the gallery will output an error, listing the missing images, and ask the user to ensure all images are correct.

To add a descritpion (starting with 1.1.c) you add '|' behind the filename:

<sgallery>
Image:picture1.jpg|This is the description for picture1
Image:picture2.png|This is the description for this one
Image3.png|This is the description for number three
</sgallery>

[edit] Live examples

You can view live working examples here.

[edit] Requirements

JonDesign's SmoothGallery
$wgUseImageResize must be enabled
May only work in Monobook skin

[edit] Installation

First of all, please always try to use the newest version. Until this extension is no longer experimental it is likely to change a bit and get a bunch of bugfixes. I will *not* support older versions as of now. It is possible to use this extension with MediaWiki 1.6, but you'll need to add a hook to includes/SkinTemplate.php called "BeforePageDisplay". Take a look at MediaWiki 1.7+ to see where you need to add it.

You'll need to perform the following steps to get SmoothGallery working:

Download SmoothGallery and untar it into your extensions directory
- Notice if you download SmoothGallery 2.0, you'll need to rename some of the javascript files; see: Extension talk:SmoothGallery#file name bug
Download the extension using the link above, and drop it into your extensions directory
Perform any required bugfixes mentioned below
Add the following lines to your LocalSettings.php file, where $wgSmoothGalleryExtensionPath is the relative URL to the SmoothGallery directory, and $wgSmoothGalleryDelimiter is the delimiter of your choosing (the default is \n):

include("extensions/SmoothGallery.php");

$wgSmoothGalleryExtensionPath = "/mediawiki/extensions/smoothgallery";

$wgSmoothGalleryDelimiter = "\n";

[edit] Fixing bugs

[edit] Fix the javascript edit toolbar

There is a MediaWiki bug in skins/common/wikibits.js that causes issues when you use Mootools.js (which SmoothGallery uses). The problem description and solution can be found here. This bug has been marked fixed, and should be included in MediaWiki 1.10+.

[edit] Fix the jd.gallery.css

The jd.gallery.css that comes from SmoothGallery has an issue when you set showarrows="false". Change:

.jdGallery a.open
{
        left: 0;
        top: 0;
        width: 100%;
        height: 100%;
}

to:

.jdGallery a.open
{
        left: 0;
        top: 0;
        /*
        width: 100%;
        height: 100%;
        */
}

[edit] Roadmap

[edit] 1.1a

Allow multiple modes of fallback when javascript isn't available including image-only, image with warning, and plain gallery.
Add support for SmoothGallery 2.0 features
Save galleries in database for use on special page
Allow image descriptions like regular galleries

[edit] 1.1b

Refactor code
- Break apart parsing and rendering (why, oh why did I do this to myself?)
- Move most functions into the class
- Try to emulate the regular gallery class, so that this plugin can be used as an API if needed
- Only create new database rows on save page, not on purge
- Recreate cache in database on purge

[edit] 1.1c

Pull out the special page and database stuff. It doesn't add much, and using wiki pages for that kind of thing is much more tested and reliable. I recommend creating a "Gallery" and "Gallery_Talk" namespace, and use those for linkable galleries.

[edit] 1.1d

Selectively turn off HistoryManager for iPhone
Fetch image list via AJAX, and preload images using SmoothGallery's built in preloader

[edit] Changelog

[edit] 1.0h

Fixed a problem with boolean values being passed incorrectly between the special page and the extension
Changed the way images are looked up. Images can now also be added like "Image:Imagename.jpg" instead of just "Imagename.jpg"

[edit] 1.0g

return true at the end of addSmoothGalleryJavascriptAndCSS(); if a hook doesn't return it can cause problems for other extensions that use the same hook

[edit] 1.0f

Changed "gmp_strval( gmp_random(1) )" to "mt_rand()" for better compatibility

[edit] 1.0e

Added a special page so that you can link to galleries instead of embedding them into pages
- You can use this like <sgallery special="linkname">imagesGoHere</sgallery>
- All options available should work in the special page
- This was tested in MediaWiki 1.6-1.9 (so it should work, tell me if not!)

[edit] 1.0d

Parse templates before rendering html

[edit] 1.0c

Now check to see if an image object is null before trying to make a thumbnail of it.

[edit] 1.0b

Added a configuration option ($wgSmoothGalleryDelimiter) to choose your own delimiter
Changed default delimiter from , to \r (it seems a comma is a valid character in image names)

[edit] 1.0a

Initial released version